fix: add MPS support for macOS Apple Silicon

Extend GPU detection to include Apple MPS backend in addition to CUDA.
This ensures macOS users with Apple Silicon use MPS acceleration
instead of being incorrectly routed to the CPU fallback path.

.github/workflows/test.yml

@@ -875,66 +875,6 @@ jobs:
         echo "=== API Server Logs ==="
         cat /tmp/api-server.log || echo "No API server log found"
 
-  test-upgrade:
-    runs-on: ubuntu-latest
-    env:
-      HINDSIGHT_API_LLM_PROVIDER: groq
-      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
-      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
-      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
-
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0  # Full history needed for git clone of tags
-
-    - name: Fetch tags
-      run: git fetch --tags
-
-    - name: Install uv
-      uses: astral-sh/setup-uv@v5
-      with:
-        enable-cache: true
-        prune-cache: false
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version-file: ".python-version"
-
-    - name: Cache HuggingFace models
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/huggingface
-        key: ${{ runner.os }}-huggingface-${{ hashFiles('hindsight-api/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-huggingface-
-
-    - name: Install hindsight-dev dependencies
-      working-directory: ./hindsight-dev
-      run: uv sync --frozen --extra test --index-strategy unsafe-best-match
-
-    - name: Install current hindsight-api
-      working-directory: ./hindsight-api
-      run: uv sync --frozen --index-strategy unsafe-best-match
-
-    - name: Pre-download models
-      working-directory: ./hindsight-api
-      run: |
-        uv run python -c "
-        from sentence_transformers import SentenceTransformer, CrossEncoder
-        print('Downloading embedding model...')
-        SentenceTransformer('BAAI/bge-small-en-v1.5')
-        print('Downloading cross-encoder model...')
-        CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')
-        print('Models downloaded successfully')
-        "
-
-    - name: Run upgrade tests
-      working-directory: ./hindsight-dev
-      run: uv run pytest upgrade_tests/ -v --tb=short
-
   verify-generated-files:
     runs-on: ubuntu-latest
     env:

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**: Consolidated knowledge synthesized from facts ("User prefers functional programming patterns")
+- **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**: Disposition-aware reasoning using memories and mental models.
+- **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.

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

@@ -1,41 +0,0 @@
-"""mental_model_id_to_text
-
-Revision ID: m8h9i0j1k2l3
-Revises: l7g8h9i0j1k2
-Create Date: 2026-01-19 00:00:00.000000
-
-This migration changes the mental_models.id column from VARCHAR(64) to TEXT
-to support longer model IDs (e.g., entity names that exceed 64 characters).
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-# revision identifiers, used by Alembic.
-revision: str = "m8h9i0j1k2l3"
-down_revision: str | Sequence[str] | None = "l7g8h9i0j1k2"
-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:
-    """Change mental_models.id from VARCHAR(64) to TEXT."""
-    schema = _get_schema_prefix()
-
-    # Alter the id column type from VARCHAR(64) to TEXT
-    op.execute(f"ALTER TABLE {schema}mental_models ALTER COLUMN id TYPE TEXT")
-
-
-def downgrade() -> None:
-    """Revert mental_models.id from TEXT to VARCHAR(64)."""
-    schema = _get_schema_prefix()
-
-    # Note: This may fail if any id values exceed 64 characters
-    op.execute(f"ALTER TABLE {schema}mental_models ALTER COLUMN id TYPE VARCHAR(64)")

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

@@ -1,134 +0,0 @@
-"""learnings_and_pinned_reflections
-
-Revision ID: n9i0j1k2l3m4
-Revises: m8h9i0j1k2l3
-Create Date: 2026-01-21 00:00:00.000000
-
-This migration:
-1. Creates the 'learnings' table for automatic bottom-up consolidation
-2. Creates the 'pinned_reflections' table for user-curated living documents
-3. Adds consolidation tracking columns to the 'banks' table
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-# revision identifiers, used by Alembic.
-revision: str = "n9i0j1k2l3m4"
-down_revision: str | Sequence[str] | None = "m8h9i0j1k2l3"
-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:
-    """Create learnings and pinned_reflections tables."""
-    schema = _get_schema_prefix()
-
-    # 1. Create learnings table
-    op.execute(f"""
-        CREATE TABLE {schema}learnings (
-            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-            bank_id VARCHAR(64) NOT NULL,
-            text TEXT NOT NULL,
-            proof_count INT NOT NULL DEFAULT 1,
-            history JSONB DEFAULT '[]'::jsonb,
-            mission_context VARCHAR(64),
-            pre_mission_change BOOLEAN DEFAULT FALSE,
-            embedding vector(384),
-            tags VARCHAR[] DEFAULT ARRAY[]::VARCHAR[],
-            created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
-            updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()
-        )
-    """)
-
-    # Add foreign key constraint
-    op.execute(f"""
-        ALTER TABLE {schema}learnings
-        ADD CONSTRAINT fk_learnings_bank_id
-        FOREIGN KEY (bank_id) REFERENCES {schema}banks(bank_id) ON DELETE CASCADE
-    """)
-
-    # Indexes for learnings
-    op.execute(f"CREATE INDEX idx_learnings_bank_id ON {schema}learnings(bank_id)")
-    op.execute(f"""
-        CREATE INDEX idx_learnings_embedding ON {schema}learnings
-        USING hnsw (embedding vector_cosine_ops)
-    """)
-    op.execute(f"CREATE INDEX idx_learnings_tags ON {schema}learnings USING GIN(tags)")
-
-    # Full-text search for learnings
-    op.execute(f"""
-        ALTER TABLE {schema}learnings ADD COLUMN search_vector tsvector
-        GENERATED ALWAYS AS (to_tsvector('english', text)) STORED
-    """)
-    op.execute(f"CREATE INDEX idx_learnings_text_search ON {schema}learnings USING gin(search_vector)")
-
-    # 2. Create pinned_reflections table
-    op.execute(f"""
-        CREATE TABLE {schema}pinned_reflections (
-            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-            bank_id VARCHAR(64) NOT NULL,
-            name VARCHAR(256) NOT NULL,
-            source_query TEXT NOT NULL,
-            content TEXT NOT NULL,
-            embedding vector(384),
-            tags VARCHAR[] DEFAULT ARRAY[]::VARCHAR[],
-            last_refreshed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
-            created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()
-        )
-    """)
-
-    # Add foreign key constraint
-    op.execute(f"""
-        ALTER TABLE {schema}pinned_reflections
-        ADD CONSTRAINT fk_pinned_reflections_bank_id
-        FOREIGN KEY (bank_id) REFERENCES {schema}banks(bank_id) ON DELETE CASCADE
-    """)
-
-    # Indexes for pinned_reflections
-    op.execute(f"CREATE INDEX idx_pinned_reflections_bank_id ON {schema}pinned_reflections(bank_id)")
-    op.execute(f"""
-        CREATE INDEX idx_pinned_reflections_embedding ON {schema}pinned_reflections
-        USING hnsw (embedding vector_cosine_ops)
-    """)
-    op.execute(f"CREATE INDEX idx_pinned_reflections_tags ON {schema}pinned_reflections USING GIN(tags)")
-
-    # Full-text search for pinned_reflections
-    op.execute(f"""
-        ALTER TABLE {schema}pinned_reflections ADD COLUMN search_vector tsvector
-        GENERATED ALWAYS AS (to_tsvector('english', COALESCE(name, '') || ' ' || content)) STORED
-    """)
-    op.execute(f"""
-        CREATE INDEX idx_pinned_reflections_text_search ON {schema}pinned_reflections
-        USING gin(search_vector)
-    """)
-
-    # 3. Add consolidation tracking columns to banks table
-    op.execute(f"""
-        ALTER TABLE {schema}banks
-        ADD COLUMN IF NOT EXISTS last_consolidated_at TIMESTAMP WITH TIME ZONE
-    """)
-    op.execute(f"""
-        ALTER TABLE {schema}banks
-        ADD COLUMN IF NOT EXISTS mission_changed_at TIMESTAMP WITH TIME ZONE
-    """)
-
-
-def downgrade() -> None:
-    """Drop learnings and pinned_reflections tables."""
-    schema = _get_schema_prefix()
-
-    # Drop tables
-    op.execute(f"DROP TABLE IF EXISTS {schema}learnings CASCADE")
-    op.execute(f"DROP TABLE IF EXISTS {schema}pinned_reflections CASCADE")
-
-    # Remove columns from banks
-    op.execute(f"ALTER TABLE {schema}banks DROP COLUMN IF EXISTS last_consolidated_at")
-    op.execute(f"ALTER TABLE {schema}banks DROP COLUMN IF EXISTS mission_changed_at")

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

@@ -1,113 +0,0 @@
-"""migrate_mental_models_data
-
-Revision ID: o0j1k2l3m4n5
-Revises: n9i0j1k2l3m4
-Create Date: 2026-01-21 00:00:00.000000
-
-This migration:
-1. Migrates existing 'pinned' mental models to the new 'pinned_reflections' table
-2. Migrates existing 'learned' mental models to the new 'learnings' table
-3. Deletes non-directive mental models (structural, emergent, pinned, learned)
-4. Drops the mental_model_versions table (no longer used)
-5. Adds a CHECK constraint that only 'directive' subtype is allowed
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-# revision identifiers, used by Alembic.
-revision: str = "o0j1k2l3m4n5"
-down_revision: str | Sequence[str] | None = "n9i0j1k2l3m4"
-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:
-    """Migrate data and clean up old mental models."""
-    schema = _get_schema_prefix()
-
-    # 1. Migrate 'pinned' mental models to pinned_reflections
-    # For pinned models, the first observation's content becomes the pinned reflection content
-    op.execute(f"""
-        INSERT INTO {schema}pinned_reflections (bank_id, name, source_query, content, tags, created_at)
-        SELECT
-            bank_id,
-            name,
-            description AS source_query,
-            COALESCE(
-                observations->'observations'->0->>'content',
-                description,
-                ''
-            ) AS content,
-            tags,
-            created_at
-        FROM {schema}mental_models
-        WHERE subtype = 'pinned'
-        ON CONFLICT DO NOTHING
-    """)
-
-    # 2. Migrate 'learned' mental models to learnings
-    # Each observation in a learned model becomes a separate learning
-    op.execute(f"""
-        INSERT INTO {schema}learnings (bank_id, text, proof_count, tags, created_at)
-        SELECT
-            mm.bank_id,
-            obs->>'content' AS text,
-            GREATEST(1, COALESCE(jsonb_array_length(obs->'evidence'), 1)) AS proof_count,
-            mm.tags,
-            mm.created_at
-        FROM {schema}mental_models mm,
-        LATERAL jsonb_array_elements(mm.observations->'observations') AS obs
-        WHERE mm.subtype = 'learned'
-          AND obs->>'content' IS NOT NULL
-          AND obs->>'content' != ''
-        ON CONFLICT DO NOTHING
-    """)
-
-    # 3. Delete all non-directive mental models (they've been migrated or are obsolete)
-    op.execute(f"""
-        DELETE FROM {schema}mental_models
-        WHERE subtype != 'directive'
-    """)
-
-    # 4. Drop the mental_model_versions table (no longer used)
-    op.execute(f"DROP TABLE IF EXISTS {schema}mental_model_versions CASCADE")
-
-    # 5. Drop old constraints and add new one that only allows 'directive'
-    op.execute(f"ALTER TABLE {schema}mental_models DROP CONSTRAINT IF EXISTS ck_mental_models_subtype")
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        ADD CONSTRAINT ck_mental_models_subtype CHECK (subtype = 'directive')
-    """)
-
-
-def downgrade() -> None:
-    """Reverse the migration (data migration is one-way, so this just removes constraints)."""
-    schema = _get_schema_prefix()
-
-    # Remove the directive-only constraint
-    op.execute(f"ALTER TABLE {schema}mental_models DROP CONSTRAINT IF EXISTS ck_mental_models_subtype")
-
-    # Re-create mental_model_versions table
-    op.execute(f"""
-        CREATE TABLE IF NOT EXISTS {schema}mental_model_versions (
-            id SERIAL PRIMARY KEY,
-            bank_id VARCHAR(64) NOT NULL,
-            model_id VARCHAR(128) NOT NULL,
-            version INT NOT NULL,
-            observations JSONB NOT NULL,
-            created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()
-        )
-    """)
-    op.execute(
-        f"CREATE INDEX IF NOT EXISTS idx_mm_versions_lookup ON {schema}mental_model_versions(bank_id, model_id, version DESC)"
-    )
-
-    # Note: Data migration cannot be reversed - pinned_reflections and learnings data remains

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

@@ -1,194 +0,0 @@
-"""new_knowledge_architecture
-
-Revision ID: p1k2l3m4n5o6
-Revises: o0j1k2l3m4n5
-Create Date: 2026-01-21 00:00:00.000000
-
-This migration implements the new knowledge architecture:
-1. Drops the 'learnings' table (mental models are now in memory_units)
-2. Renames 'pinned_reflections' to 'reflections'
-3. Drops the 'mental_models' table completely
-4. Creates 'directives' table for hard rules
-5. Adds mental model support columns to 'memory_units' (proof_count, source_memory_ids, history)
-
-The new architecture:
-- Directives: Hard rules in their own table
-- Mental Models: Stored in memory_units with fact_type='mental_model'
-- Reflections: User-curated documents (renamed from pinned_reflections)
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-# revision identifiers, used by Alembic.
-revision: str = "p1k2l3m4n5o6"
-down_revision: str | Sequence[str] | None = "o0j1k2l3m4n5"
-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:
-    """Implement new knowledge architecture."""
-    schema = _get_schema_prefix()
-
-    # 1. Drop the learnings table (mental models will be in memory_units)
-    op.execute(f"DROP TABLE IF EXISTS {schema}learnings CASCADE")
-
-    # 2. Rename pinned_reflections to reflections
-    op.execute(f"ALTER TABLE IF EXISTS {schema}pinned_reflections RENAME TO reflections")
-
-    # Rename indexes for reflections
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_pinned_reflections_bank_id RENAME TO idx_reflections_bank_id")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_pinned_reflections_embedding RENAME TO idx_reflections_embedding")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_pinned_reflections_tags RENAME TO idx_reflections_tags")
-    op.execute(
-        f"ALTER INDEX IF EXISTS {schema}idx_pinned_reflections_text_search RENAME TO idx_reflections_text_search"
-    )
-
-    # Rename foreign key constraint
-    op.execute(f"""
-        ALTER TABLE {schema}reflections
-        DROP CONSTRAINT IF EXISTS fk_pinned_reflections_bank_id
-    """)
-    op.execute(f"""
-        ALTER TABLE {schema}reflections
-        ADD CONSTRAINT fk_reflections_bank_id
-        FOREIGN KEY (bank_id) REFERENCES {schema}banks(bank_id) ON DELETE CASCADE
-    """)
-
-    # 3. Drop the mental_models table completely
-    op.execute(f"DROP TABLE IF EXISTS {schema}mental_models CASCADE")
-
-    # 4. Create directives table
-    op.execute(f"""
-        CREATE TABLE {schema}directives (
-            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-            bank_id VARCHAR(64) NOT NULL,
-            name VARCHAR(256) NOT NULL,
-            content TEXT NOT NULL,
-            priority INT NOT NULL DEFAULT 0,
-            is_active BOOLEAN NOT NULL DEFAULT TRUE,
-            tags VARCHAR[] DEFAULT ARRAY[]::VARCHAR[],
-            created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
-            updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()
-        )
-    """)
-
-    # Add foreign key and indexes for directives
-    op.execute(f"""
-        ALTER TABLE {schema}directives
-        ADD CONSTRAINT fk_directives_bank_id
-        FOREIGN KEY (bank_id) REFERENCES {schema}banks(bank_id) ON DELETE CASCADE
-    """)
-    op.execute(f"CREATE INDEX idx_directives_bank_id ON {schema}directives(bank_id)")
-    op.execute(f"CREATE INDEX idx_directives_bank_active ON {schema}directives(bank_id, is_active)")
-    op.execute(f"CREATE INDEX idx_directives_tags ON {schema}directives USING GIN(tags)")
-
-    # 5. Add mental model support columns to memory_units
-    # proof_count: Number of memories that support this mental model
-    op.execute(f"""
-        ALTER TABLE {schema}memory_units
-        ADD COLUMN IF NOT EXISTS proof_count INT DEFAULT 1
-    """)
-
-    # source_memory_ids: Array of memory IDs that consolidated into this mental model
-    op.execute(f"""
-        ALTER TABLE {schema}memory_units
-        ADD COLUMN IF NOT EXISTS source_memory_ids UUID[] DEFAULT ARRAY[]::UUID[]
-    """)
-
-    # history: JSONB array tracking changes to mental models
-    op.execute(f"""
-        ALTER TABLE {schema}memory_units
-        ADD COLUMN IF NOT EXISTS history JSONB DEFAULT '[]'::jsonb
-    """)
-
-    # Add index for finding mental models
-    op.execute(f"""
-        CREATE INDEX IF NOT EXISTS idx_memory_units_mental_models
-        ON {schema}memory_units(bank_id, fact_type)
-        WHERE fact_type = 'mental_model'
-    """)
-
-    # 6. Update fact_type check constraint to include 'mental_model'
-    op.execute(f"ALTER TABLE {schema}memory_units DROP CONSTRAINT IF EXISTS memory_units_fact_type_check")
-    op.execute(f"""
-        ALTER TABLE {schema}memory_units
-        ADD CONSTRAINT memory_units_fact_type_check
-        CHECK (fact_type IN ('world', 'experience', 'opinion', 'observation', 'mental_model'))
-    """)
-
-
-def downgrade() -> None:
-    """Reverse the migration."""
-    schema = _get_schema_prefix()
-
-    # Restore original fact_type check constraint (without 'mental_model')
-    op.execute(f"ALTER TABLE {schema}memory_units DROP CONSTRAINT IF EXISTS memory_units_fact_type_check")
-    op.execute(f"""
-        ALTER TABLE {schema}memory_units
-        ADD CONSTRAINT memory_units_fact_type_check
-        CHECK (fact_type IN ('world', 'experience', 'opinion', 'observation'))
-    """)
-
-    # Drop mental model columns from memory_units
-    op.execute(f"ALTER TABLE {schema}memory_units DROP COLUMN IF EXISTS proof_count")
-    op.execute(f"ALTER TABLE {schema}memory_units DROP COLUMN IF EXISTS source_memory_ids")
-    op.execute(f"ALTER TABLE {schema}memory_units DROP COLUMN IF EXISTS history")
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_memory_units_mental_models")
-
-    # Drop directives table
-    op.execute(f"DROP TABLE IF EXISTS {schema}directives CASCADE")
-
-    # Rename reflections back to pinned_reflections
-    op.execute(f"ALTER TABLE IF EXISTS {schema}reflections RENAME TO pinned_reflections")
-
-    # Restore indexes
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_reflections_bank_id RENAME TO idx_pinned_reflections_bank_id")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_reflections_embedding RENAME TO idx_pinned_reflections_embedding")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_reflections_tags RENAME TO idx_pinned_reflections_tags")
-    op.execute(
-        f"ALTER INDEX IF EXISTS {schema}idx_reflections_text_search RENAME TO idx_pinned_reflections_text_search"
-    )
-
-    # Restore foreign key
-    op.execute(f"""
-        ALTER TABLE {schema}pinned_reflections
-        DROP CONSTRAINT IF EXISTS fk_reflections_bank_id
-    """)
-    op.execute(f"""
-        ALTER TABLE {schema}pinned_reflections
-        ADD CONSTRAINT fk_pinned_reflections_bank_id
-        FOREIGN KEY (bank_id) REFERENCES {schema}banks(bank_id) ON DELETE CASCADE
-    """)
-
-    # Re-create learnings table
-    op.execute(f"""
-        CREATE TABLE IF NOT EXISTS {schema}learnings (
-            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-            bank_id VARCHAR(64) NOT NULL,
-            text TEXT NOT NULL,
-            proof_count INT NOT NULL DEFAULT 1,
-            history JSONB DEFAULT '[]'::jsonb,
-            mission_context VARCHAR(64),
-            pre_mission_change BOOLEAN DEFAULT FALSE,
-            embedding vector(384),
-            tags VARCHAR[] DEFAULT ARRAY[]::VARCHAR[],
-            created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
-            updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()
-        )
-    """)
-    op.execute(f"""
-        ALTER TABLE {schema}learnings
-        ADD CONSTRAINT fk_learnings_bank_id
-        FOREIGN KEY (bank_id) REFERENCES {schema}banks(bank_id) ON DELETE CASCADE
-    """)
-
-    # Note: mental_models table recreation is complex and would need separate handling

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

@@ -1,50 +0,0 @@
-"""fix_mental_model_fact_type
-
-Revision ID: q2l3m4n5o6p7
-Revises: p1k2l3m4n5o6
-Create Date: 2026-01-21 13:30:00.000000
-
-Fix the fact_type check constraint to include 'mental_model'.
-This is a fix for p1k2l3m4n5o6 which should have included this change.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-# revision identifiers, used by Alembic.
-revision: str = "q2l3m4n5o6p7"
-down_revision: str | Sequence[str] | None = "p1k2l3m4n5o6"
-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 'mental_model' to the fact_type check constraint."""
-    schema = _get_schema_prefix()
-
-    # Drop the old constraint and add the new one with mental_model included
-    op.execute(f"ALTER TABLE {schema}memory_units DROP CONSTRAINT IF EXISTS memory_units_fact_type_check")
-    op.execute(f"""
-        ALTER TABLE {schema}memory_units
-        ADD CONSTRAINT memory_units_fact_type_check
-        CHECK (fact_type IN ('world', 'experience', 'opinion', 'observation', 'mental_model'))
-    """)
-
-
-def downgrade() -> None:
-    """Remove 'mental_model' from the fact_type check constraint."""
-    schema = _get_schema_prefix()
-
-    op.execute(f"ALTER TABLE {schema}memory_units DROP CONSTRAINT IF EXISTS memory_units_fact_type_check")
-    op.execute(f"""
-        ALTER TABLE {schema}memory_units
-        ADD CONSTRAINT memory_units_fact_type_check
-        CHECK (fact_type IN ('world', 'experience', 'opinion', 'observation'))
-    """)

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

@@ -1,47 +0,0 @@
-"""Add reflect_response JSONB column to reflections
-
-Revision ID: r3m4n5o6p7q8
-Revises: q2l3m4n5o6p7
-Create Date: 2026-01-21
-
-This migration adds a reflect_response JSONB column to store the full
-reflect API response payload, including based_on facts and trace data.
-
-Note: Table was renamed from pinned_reflections to reflections in p1k2l3m4n5o6.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "r3m4n5o6p7q8"
-down_revision: str | Sequence[str] | None = "q2l3m4n5o6p7"
-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 reflect_response JSONB column to reflections."""
-    schema = _get_schema_prefix()
-
-    # Add reflect_response column to store the full reflect API response
-    op.execute(f"""
-        ALTER TABLE {schema}reflections
-        ADD COLUMN IF NOT EXISTS reflect_response JSONB
-    """)
-
-
-def downgrade() -> None:
-    """Remove reflect_response column from reflections."""
-    schema = _get_schema_prefix()
-
-    op.execute(f"""
-        ALTER TABLE {schema}reflections
-        DROP COLUMN IF EXISTS reflect_response
-    """)

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

@@ -1,53 +0,0 @@
-"""Add consolidated_at column to memory_units for incremental consolidation tracking.
-
-This allows consolidation to track progress at the memory level rather than
-using a bank-level watermark. If consolidation crashes, already-processed
-memories won't be reprocessed.
-
-Revision ID: s4n5o6p7q8r9
-Revises: r3m4n5o6p7q8
-Create Date: 2025-01-22
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "s4n5o6p7q8r9"
-down_revision: str | Sequence[str] | None = "r3m4n5o6p7q8"
-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:
-    schema = _get_schema_prefix()
-
-    # Add consolidated_at column to memory_units
-    op.execute(
-        f"""
-        ALTER TABLE {schema}memory_units
-        ADD COLUMN IF NOT EXISTS consolidated_at TIMESTAMPTZ DEFAULT NULL
-        """
-    )
-
-    # Create index for efficient querying of unconsolidated memories
-    op.execute(
-        f"""
-        CREATE INDEX IF NOT EXISTS idx_memory_units_unconsolidated
-        ON {schema}memory_units (bank_id, created_at)
-        WHERE consolidated_at IS NULL AND fact_type IN ('experience', 'world')
-        """
-    )
-
-
-def downgrade() -> None:
-    schema = _get_schema_prefix()
-
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_memory_units_unconsolidated")
-    op.execute(f"ALTER TABLE {schema}memory_units DROP COLUMN IF EXISTS consolidated_at")

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

@@ -1,134 +0,0 @@
-"""Rename mental_model fact_type to observation and reflections table to mental_models
-
-Revision ID: t5o6p7q8r9s0
-Revises: s4n5o6p7q8r9
-Create Date: 2026-01-26
-
-This migration implements the terminology rename:
-1. mental_model (fact_type in memory_units) -> observation
-2. reflections table -> mental_models table
-
-The new terminology:
-- Observations: Consolidated knowledge synthesized from facts (was mental_model)
-- Mental Models: Stored reflect responses (was reflections)
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "t5o6p7q8r9s0"
-down_revision: str | Sequence[str] | None = "s4n5o6p7q8r9"
-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:
-    """Rename mental_model -> observation and reflections -> mental_models."""
-    schema = _get_schema_prefix()
-
-    # 1. Update fact_type values: mental_model -> observation
-    op.execute(f"""
-        UPDATE {schema}memory_units
-        SET fact_type = 'observation'
-        WHERE fact_type = 'mental_model'
-    """)
-
-    # 2. Update the CHECK constraint - remove mental_model, keep observation
-    op.execute(f"ALTER TABLE {schema}memory_units DROP CONSTRAINT IF EXISTS memory_units_fact_type_check")
-    op.execute(f"""
-        ALTER TABLE {schema}memory_units
-        ADD CONSTRAINT memory_units_fact_type_check
-        CHECK (fact_type IN ('world', 'experience', 'opinion', 'observation'))
-    """)
-
-    # 3. Rename the index for observations (was for mental_models)
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_memory_units_mental_models")
-    op.execute(f"""
-        CREATE INDEX IF NOT EXISTS idx_memory_units_observations
-        ON {schema}memory_units(bank_id, fact_type)
-        WHERE fact_type = 'observation'
-    """)
-
-    # 4. Update the unconsolidated index to not filter by fact_type since observations
-    # are now the consolidated type
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_memory_units_unconsolidated")
-    op.execute(f"""
-        CREATE INDEX IF NOT EXISTS idx_memory_units_unconsolidated
-        ON {schema}memory_units (bank_id, created_at)
-        WHERE consolidated_at IS NULL AND fact_type IN ('experience', 'world')
-    """)
-
-    # 5. Rename reflections table to mental_models
-    op.execute(f"ALTER TABLE IF EXISTS {schema}reflections RENAME TO mental_models")
-
-    # 6. Rename indexes for mental_models (was reflections)
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_reflections_bank_id RENAME TO idx_mental_models_bank_id")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_reflections_embedding RENAME TO idx_mental_models_embedding")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_reflections_tags RENAME TO idx_mental_models_tags")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_reflections_text_search RENAME TO idx_mental_models_text_search")
-
-    # 7. Rename foreign key constraint
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        DROP CONSTRAINT IF EXISTS fk_reflections_bank_id
-    """)
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        ADD CONSTRAINT fk_mental_models_bank_id
-        FOREIGN KEY (bank_id) REFERENCES {schema}banks(bank_id) ON DELETE CASCADE
-    """)
-
-
-def downgrade() -> None:
-    """Reverse: observation -> mental_model and mental_models -> reflections."""
-    schema = _get_schema_prefix()
-
-    # 1. Rename mental_models table back to reflections
-    op.execute(f"ALTER TABLE IF EXISTS {schema}mental_models RENAME TO reflections")
-
-    # 2. Rename indexes back
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_mental_models_bank_id RENAME TO idx_reflections_bank_id")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_mental_models_embedding RENAME TO idx_reflections_embedding")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_mental_models_tags RENAME TO idx_reflections_tags")
-    op.execute(f"ALTER INDEX IF EXISTS {schema}idx_mental_models_text_search RENAME TO idx_reflections_text_search")
-
-    # 3. Rename foreign key back
-    op.execute(f"""
-        ALTER TABLE {schema}reflections
-        DROP CONSTRAINT IF EXISTS fk_mental_models_bank_id
-    """)
-    op.execute(f"""
-        ALTER TABLE {schema}reflections
-        ADD CONSTRAINT fk_reflections_bank_id
-        FOREIGN KEY (bank_id) REFERENCES {schema}banks(bank_id) ON DELETE CASCADE
-    """)
-
-    # 4. Update fact_type values: observation -> mental_model
-    op.execute(f"""
-        UPDATE {schema}memory_units
-        SET fact_type = 'mental_model'
-        WHERE fact_type = 'observation'
-    """)
-
-    # 5. Update the CHECK constraint back
-    op.execute(f"ALTER TABLE {schema}memory_units DROP CONSTRAINT IF EXISTS memory_units_fact_type_check")
-    op.execute(f"""
-        ALTER TABLE {schema}memory_units
-        ADD CONSTRAINT memory_units_fact_type_check
-        CHECK (fact_type IN ('world', 'experience', 'opinion', 'observation', 'mental_model'))
-    """)
-
-    # 6. Rename index back
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_memory_units_observations")
-    op.execute(f"""
-        CREATE INDEX IF NOT EXISTS idx_memory_units_mental_models
-        ON {schema}memory_units(bank_id, fact_type)
-        WHERE fact_type = 'mental_model'
-    """)

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

@@ -1,41 +0,0 @@
-"""Change mental_models.id from UUID to TEXT
-
-Revision ID: u6p7q8r9s0t1
-Revises: t5o6p7q8r9s0
-Create Date: 2026-01-27
-
-This migration changes the mental_models.id column from UUID to TEXT
-to support user-defined text identifiers like 'team-communication' instead of UUIDs.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "u6p7q8r9s0t1"
-down_revision: str | Sequence[str] | None = "t5o6p7q8r9s0"
-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:
-    """Change mental_models.id from UUID to TEXT."""
-    schema = _get_schema_prefix()
-
-    # Change the id column type from UUID to TEXT
-    # Existing UUIDs will be converted to their string representation
-    op.execute(f"ALTER TABLE {schema}mental_models ALTER COLUMN id TYPE TEXT USING id::TEXT")
-
-
-def downgrade() -> None:
-    """Revert mental_models.id from TEXT to UUID."""
-    schema = _get_schema_prefix()
-
-    # Note: This will fail if any id values are not valid UUIDs
-    op.execute(f"ALTER TABLE {schema}mental_models ALTER COLUMN id TYPE UUID USING id::UUID")

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

@@ -1,50 +0,0 @@
-"""Add max_tokens and trigger columns to mental_models
-
-Revision ID: v7q8r9s0t1u2
-Revises: u6p7q8r9s0t1
-Create Date: 2026-01-27
-
-This migration adds:
-- max_tokens column: token limit for content generation during refresh
-- trigger column: JSONB for trigger settings (e.g., refresh_after_consolidation)
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "v7q8r9s0t1u2"
-down_revision: str | Sequence[str] | None = "u6p7q8r9s0t1"
-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 max_tokens and trigger columns to mental_models."""
-    schema = _get_schema_prefix()
-
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        ADD COLUMN IF NOT EXISTS max_tokens INT NOT NULL DEFAULT 2048
-    """)
-
-    # trigger column stores trigger settings as JSONB
-    # Default: refresh_after_consolidation = false (not "real time")
-    op.execute(f"""
-        ALTER TABLE {schema}mental_models
-        ADD COLUMN IF NOT EXISTS trigger JSONB NOT NULL DEFAULT '{{"refresh_after_consolidation": false}}'::jsonb
-    """)
-
-
-def downgrade() -> None:
-    """Remove max_tokens and trigger columns from mental_models."""
-    schema = _get_schema_prefix()
-
-    op.execute(f"ALTER TABLE {schema}mental_models DROP COLUMN IF EXISTS max_tokens")
-    op.execute(f"ALTER TABLE {schema}mental_models DROP COLUMN IF EXISTS trigger")

hindsight-api/hindsight_api/api/mcp.py

@@ -1,4 +1,4 @@
-"""Hindsight MCP Server implementation using FastMCP (HTTP transport)."""
+"""Hindsight MCP Server implementation using FastMCP."""
 
 import json
 import logging
@@ -8,7 +8,8 @@ from contextvars import ContextVar
 from fastmcp import FastMCP
 
 from hindsight_api import MemoryEngine
-from hindsight_api.mcp_tools import MCPToolsConfig, register_mcp_tools
+from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES
+from hindsight_api.models import RequestContext
 
 # Configure logging from HINDSIGHT_API_LOG_LEVEL environment variable
 _log_level_str = os.environ.get("HINDSIGHT_API_LOG_LEVEL", "info").lower()
@@ -51,15 +52,194 @@ def create_mcp_server(memory: MemoryEngine) -> FastMCP:
     # Use stateless_http=True for Claude Code compatibility
     mcp = FastMCP("hindsight-mcp-server", stateless_http=True)
 
-    # Configure and register tools using shared module
-    config = MCPToolsConfig(
-        bank_id_resolver=get_current_bank_id,
-        include_bank_id_param=True,  # HTTP MCP supports multi-bank via parameter
-        tools=None,  # All tools
-        retain_fire_and_forget=False,  # HTTP MCP supports sync/async modes
-    )
+    @mcp.tool()
+    async def retain(
+        content: str,
+        context: str = "general",
+        async_processing: bool = True,
+        bank_id: str | None = None,
+    ) -> str:
+        """
+        Store important information to long-term memory.
 
-    register_mcp_tools(mcp, memory, config)
+        Use this tool PROACTIVELY whenever the user shares:
+        - Personal facts, preferences, or interests
+        - Important events or milestones
+        - User history, experiences, or background
+        - Decisions, opinions, or stated preferences
+        - Goals, plans, or future intentions
+        - Relationships or people mentioned
+        - Work context, projects, or responsibilities
+
+        Args:
+            content: The fact/memory to store (be specific and include relevant details)
+            context: Category for the memory (e.g., 'preferences', 'work', 'hobbies', 'family'). Default: 'general'
+            async_processing: If True, queue for background processing and return immediately. If False, wait for completion. Default: True
+            bank_id: Optional bank to store in (defaults to session bank). Use for cross-bank operations.
+        """
+        try:
+            target_bank = bank_id or get_current_bank_id()
+            if target_bank is None:
+                return "Error: No bank_id configured"
+            contents = [{"content": content, "context": context}]
+            if async_processing:
+                # Queue for background processing and return immediately
+                result = await memory.submit_async_retain(
+                    bank_id=target_bank, contents=contents, request_context=RequestContext()
+                )
+                return f"Memory queued for background processing (operation_id: {result.get('operation_id', 'N/A')})"
+            else:
+                # Wait for completion
+                await memory.retain_batch_async(
+                    bank_id=target_bank,
+                    contents=contents,
+                    request_context=RequestContext(),
+                )
+                return f"Memory stored successfully in bank '{target_bank}'"
+        except Exception as e:
+            logger.error(f"Error storing memory: {e}", exc_info=True)
+            return f"Error: {str(e)}"
+
+    @mcp.tool()
+    async def recall(query: str, max_tokens: int = 4096, bank_id: str | None = None) -> str:
+        """
+        Search memories to provide personalized, context-aware responses.
+
+        Use this tool PROACTIVELY to:
+        - Check user's preferences before making suggestions
+        - Recall user's history to provide continuity
+        - Remember user's goals and context
+        - Personalize responses based on past interactions
+
+        Args:
+            query: Natural language search query (e.g., "user's food preferences", "what projects is user working on")
+            max_tokens: Maximum tokens in the response (default: 4096)
+            bank_id: Optional bank to search in (defaults to session bank). Use for cross-bank operations.
+        """
+        try:
+            target_bank = bank_id or get_current_bank_id()
+            if target_bank is None:
+                return "Error: No bank_id configured"
+            from hindsight_api.engine.memory_engine import Budget
+
+            recall_result = await memory.recall_async(
+                bank_id=target_bank,
+                query=query,
+                fact_type=list(VALID_RECALL_FACT_TYPES),
+                budget=Budget.HIGH,
+                max_tokens=max_tokens,
+                request_context=RequestContext(),
+            )
+
+            # Use model's JSON serialization
+            return recall_result.model_dump_json(indent=2)
+        except Exception as e:
+            logger.error(f"Error searching: {e}", exc_info=True)
+            return f'{{"error": "{e}", "results": []}}'
+
+    @mcp.tool()
+    async def reflect(query: str, context: str | None = None, budget: str = "low", bank_id: str | None = None) -> str:
+        """
+        Generate thoughtful analysis by synthesizing stored memories with the bank's personality.
+
+        WHEN TO USE THIS TOOL:
+        Use reflect when you need reasoned analysis, not just fact retrieval. This tool
+        thinks through the question using everything the bank knows and its personality traits.
+
+        EXAMPLES OF GOOD QUERIES:
+        - "What patterns have emerged in how I approach debugging?"
+        - "Based on my past decisions, what architectural style do I prefer?"
+        - "What might be the best approach for this problem given what you know about me?"
+        - "How should I prioritize these tasks based on my goals?"
+
+        HOW IT DIFFERS FROM RECALL:
+        - recall: Returns raw facts matching your search (fast lookup)
+        - reflect: Reasons across memories to form a synthesized answer (deeper analysis)
+
+        Use recall for "what did I say about X?" and reflect for "what should I do about X?"
+
+        Args:
+            query: The question or topic to reflect on
+            context: Optional context about why this reflection is needed
+            budget: Search budget - 'low', 'mid', or 'high' (default: 'low')
+            bank_id: Optional bank to reflect in (defaults to session bank). Use for cross-bank operations.
+        """
+        try:
+            target_bank = bank_id or get_current_bank_id()
+            if target_bank is None:
+                return "Error: No bank_id configured"
+            from hindsight_api.engine.memory_engine import Budget
+
+            # Map string budget to enum
+            budget_map = {"low": Budget.LOW, "mid": Budget.MID, "high": Budget.HIGH}
+            budget_enum = budget_map.get(budget.lower(), Budget.LOW)
+
+            reflect_result = await memory.reflect_async(
+                bank_id=target_bank,
+                query=query,
+                budget=budget_enum,
+                context=context,
+                request_context=RequestContext(),
+            )
+
+            return reflect_result.model_dump_json(indent=2)
+        except Exception as e:
+            logger.error(f"Error reflecting: {e}", exc_info=True)
+            return f'{{"error": "{e}", "text": ""}}'
+
+    @mcp.tool()
+    async def list_banks() -> str:
+        """
+        List all available memory banks.
+
+        Use this tool to discover what memory banks exist in the system.
+        Each bank is an isolated memory store (like a separate "brain").
+
+        Returns:
+            JSON list of banks with their IDs, names, dispositions, and missions.
+        """
+        try:
+            banks = await memory.list_banks(request_context=RequestContext())
+            return json.dumps({"banks": banks}, indent=2)
+        except Exception as e:
+            logger.error(f"Error listing banks: {e}", exc_info=True)
+            return f'{{"error": "{e}", "banks": []}}'
+
+    @mcp.tool()
+    async def create_bank(bank_id: str, name: str | None = None, mission: str | None = None) -> str:
+        """
+        Create a new memory bank or get an existing one.
+
+        Memory banks are isolated stores - each one is like a separate "brain" for a user/agent.
+        Banks are auto-created with default settings if they don't exist.
+
+        Args:
+            bank_id: Unique identifier for the bank (e.g., 'user-123', 'agent-alpha')
+            name: Optional human-friendly name for the bank
+            mission: Optional mission describing who the agent is and what they're trying to accomplish
+        """
+        try:
+            # get_bank_profile auto-creates bank if it doesn't exist
+            profile = await memory.get_bank_profile(bank_id, request_context=RequestContext())
+
+            # Update name/mission if provided
+            if name is not None or mission is not None:
+                await memory.update_bank(
+                    bank_id,
+                    name=name,
+                    mission=mission,
+                    request_context=RequestContext(),
+                )
+                # Fetch updated profile
+                profile = await memory.get_bank_profile(bank_id, request_context=RequestContext())
+
+            # Serialize disposition if it's a Pydantic model
+            if "disposition" in profile and hasattr(profile["disposition"], "model_dump"):
+                profile["disposition"] = profile["disposition"].model_dump()
+            return json.dumps(profile, indent=2)
+        except Exception as e:
+            logger.error(f"Error creating bank: {e}", exc_info=True)
+            return f'{{"error": "{e}"}}'
 
     return mcp
 

hindsight-api/hindsight_api/config.py

@@ -39,11 +39,6 @@ ENV_REFLECT_LLM_API_KEY = "HINDSIGHT_API_REFLECT_LLM_API_KEY"
 ENV_REFLECT_LLM_MODEL = "HINDSIGHT_API_REFLECT_LLM_MODEL"
 ENV_REFLECT_LLM_BASE_URL = "HINDSIGHT_API_REFLECT_LLM_BASE_URL"
 
-ENV_CONSOLIDATION_LLM_PROVIDER = "HINDSIGHT_API_CONSOLIDATION_LLM_PROVIDER"
-ENV_CONSOLIDATION_LLM_API_KEY = "HINDSIGHT_API_CONSOLIDATION_LLM_API_KEY"
-ENV_CONSOLIDATION_LLM_MODEL = "HINDSIGHT_API_CONSOLIDATION_LLM_MODEL"
-ENV_CONSOLIDATION_LLM_BASE_URL = "HINDSIGHT_API_CONSOLIDATION_LLM_BASE_URL"
-
 ENV_EMBEDDINGS_PROVIDER = "HINDSIGHT_API_EMBEDDINGS_PROVIDER"
 ENV_EMBEDDINGS_LOCAL_MODEL = "HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL"
 ENV_EMBEDDINGS_TEI_URL = "HINDSIGHT_API_EMBEDDINGS_TEI_URL"
@@ -87,18 +82,17 @@ ENV_MCP_LOCAL_BANK_ID = "HINDSIGHT_API_MCP_LOCAL_BANK_ID"
 ENV_MCP_INSTRUCTIONS = "HINDSIGHT_API_MCP_INSTRUCTIONS"
 ENV_MENTAL_MODEL_REFRESH_CONCURRENCY = "HINDSIGHT_API_MENTAL_MODEL_REFRESH_CONCURRENCY"
 
+# Observation thresholds
+ENV_OBSERVATION_MIN_FACTS = "HINDSIGHT_API_OBSERVATION_MIN_FACTS"
+ENV_OBSERVATION_TOP_ENTITIES = "HINDSIGHT_API_OBSERVATION_TOP_ENTITIES"
+
 # Retain settings
 ENV_RETAIN_MAX_COMPLETION_TOKENS = "HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS"
 ENV_RETAIN_CHUNK_SIZE = "HINDSIGHT_API_RETAIN_CHUNK_SIZE"
 ENV_RETAIN_EXTRACT_CAUSAL_LINKS = "HINDSIGHT_API_RETAIN_EXTRACT_CAUSAL_LINKS"
 ENV_RETAIN_EXTRACTION_MODE = "HINDSIGHT_API_RETAIN_EXTRACTION_MODE"
-ENV_RETAIN_CUSTOM_INSTRUCTIONS = "HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS"
 ENV_RETAIN_OBSERVATIONS_ASYNC = "HINDSIGHT_API_RETAIN_OBSERVATIONS_ASYNC"
 
-# Observations settings (consolidated knowledge from facts)
-ENV_ENABLE_OBSERVATIONS = "HINDSIGHT_API_ENABLE_OBSERVATIONS"
-ENV_CONSOLIDATION_BATCH_SIZE = "HINDSIGHT_API_CONSOLIDATION_BATCH_SIZE"
-
 # Optimization flags
 ENV_SKIP_LLM_VERIFICATION = "HINDSIGHT_API_SKIP_LLM_VERIFICATION"
 ENV_LAZY_RERANKER = "HINDSIGHT_API_LAZY_RERANKER"
@@ -165,19 +159,18 @@ DEFAULT_RECALL_CONNECTION_BUDGET = 4  # Max concurrent DB connections per recall
 DEFAULT_MCP_LOCAL_BANK_ID = "mcp"
 DEFAULT_MENTAL_MODEL_REFRESH_CONCURRENCY = 8  # Max concurrent mental model refreshes
 
+# Observation thresholds
+DEFAULT_OBSERVATION_MIN_FACTS = 5  # Min facts required to generate entity observations
+DEFAULT_OBSERVATION_TOP_ENTITIES = 5  # Max entities to process per retain batch
+
 # Retain settings
 DEFAULT_RETAIN_MAX_COMPLETION_TOKENS = 64000  # Max tokens for fact extraction LLM call
 DEFAULT_RETAIN_CHUNK_SIZE = 3000  # Max chars per chunk for fact extraction
 DEFAULT_RETAIN_EXTRACT_CAUSAL_LINKS = True  # Extract causal links between facts
-DEFAULT_RETAIN_EXTRACTION_MODE = "concise"  # Extraction mode: "concise", "verbose", or "custom"
-RETAIN_EXTRACTION_MODES = ("concise", "verbose", "custom")  # Allowed extraction modes
-DEFAULT_RETAIN_CUSTOM_INSTRUCTIONS = None  # Custom extraction guidelines (only used when mode="custom")
+DEFAULT_RETAIN_EXTRACTION_MODE = "concise"  # Extraction mode: "concise" or "verbose"
+RETAIN_EXTRACTION_MODES = ("concise", "verbose")  # Allowed extraction modes
 DEFAULT_RETAIN_OBSERVATIONS_ASYNC = False  # Run observation generation async (after retain completes)
 
-# Observations defaults (consolidated knowledge from facts)
-DEFAULT_ENABLE_OBSERVATIONS = True  # Observations enabled by default
-DEFAULT_CONSOLIDATION_BATCH_SIZE = 50  # Memories to load per batch (internal memory optimization)
-
 # Database migrations
 DEFAULT_RUN_MIGRATIONS_ON_STARTUP = True
 
@@ -290,11 +283,6 @@ class HindsightConfig:
     reflect_llm_model: str | None
     reflect_llm_base_url: str | None
 
-    consolidation_llm_provider: str | None
-    consolidation_llm_api_key: str | None
-    consolidation_llm_model: str | None
-    consolidation_llm_base_url: str | None
-
     # Embeddings
     embeddings_provider: str
     embeddings_local_model: str
@@ -325,18 +313,17 @@ class HindsightConfig:
     recall_connection_budget: int
     mental_model_refresh_concurrency: int
 
+    # Observation thresholds
+    observation_min_facts: int
+    observation_top_entities: int
+
     # Retain settings
     retain_max_completion_tokens: int
     retain_chunk_size: int
     retain_extract_causal_links: bool
     retain_extraction_mode: str
-    retain_custom_instructions: str | None
     retain_observations_async: bool
 
-    # Observations settings (consolidated knowledge from facts)
-    enable_observations: bool
-    consolidation_batch_size: int
-
     # Optimization flags
     skip_llm_verification: bool
     lazy_reranker: bool
@@ -383,10 +370,6 @@ class HindsightConfig:
             reflect_llm_api_key=os.getenv(ENV_REFLECT_LLM_API_KEY) or None,
             reflect_llm_model=os.getenv(ENV_REFLECT_LLM_MODEL) or None,
             reflect_llm_base_url=os.getenv(ENV_REFLECT_LLM_BASE_URL) or None,
-            consolidation_llm_provider=os.getenv(ENV_CONSOLIDATION_LLM_PROVIDER) or None,
-            consolidation_llm_api_key=os.getenv(ENV_CONSOLIDATION_LLM_API_KEY) or None,
-            consolidation_llm_model=os.getenv(ENV_CONSOLIDATION_LLM_MODEL) or None,
-            consolidation_llm_base_url=os.getenv(ENV_CONSOLIDATION_LLM_BASE_URL) or None,
             # Embeddings
             embeddings_provider=os.getenv(ENV_EMBEDDINGS_PROVIDER, DEFAULT_EMBEDDINGS_PROVIDER),
             embeddings_local_model=os.getenv(ENV_EMBEDDINGS_LOCAL_MODEL, DEFAULT_EMBEDDINGS_LOCAL_MODEL),
@@ -422,6 +405,11 @@ class HindsightConfig:
             # Optimization flags
             skip_llm_verification=os.getenv(ENV_SKIP_LLM_VERIFICATION, "false").lower() == "true",
             lazy_reranker=os.getenv(ENV_LAZY_RERANKER, "false").lower() == "true",
+            # Observation thresholds
+            observation_min_facts=int(os.getenv(ENV_OBSERVATION_MIN_FACTS, str(DEFAULT_OBSERVATION_MIN_FACTS))),
+            observation_top_entities=int(
+                os.getenv(ENV_OBSERVATION_TOP_ENTITIES, str(DEFAULT_OBSERVATION_TOP_ENTITIES))
+            ),
             # Retain settings
             retain_max_completion_tokens=int(
                 os.getenv(ENV_RETAIN_MAX_COMPLETION_TOKENS, str(DEFAULT_RETAIN_MAX_COMPLETION_TOKENS))
@@ -434,16 +422,10 @@ class HindsightConfig:
             retain_extraction_mode=_validate_extraction_mode(
                 os.getenv(ENV_RETAIN_EXTRACTION_MODE, DEFAULT_RETAIN_EXTRACTION_MODE)
             ),
-            retain_custom_instructions=os.getenv(ENV_RETAIN_CUSTOM_INSTRUCTIONS) or DEFAULT_RETAIN_CUSTOM_INSTRUCTIONS,
             retain_observations_async=os.getenv(
                 ENV_RETAIN_OBSERVATIONS_ASYNC, str(DEFAULT_RETAIN_OBSERVATIONS_ASYNC)
             ).lower()
             == "true",
-            # Observations settings (consolidated knowledge from facts)
-            enable_observations=os.getenv(ENV_ENABLE_OBSERVATIONS, str(DEFAULT_ENABLE_OBSERVATIONS)).lower() == "true",
-            consolidation_batch_size=int(
-                os.getenv(ENV_CONSOLIDATION_BATCH_SIZE, str(DEFAULT_CONSOLIDATION_BATCH_SIZE))
-            ),
             # Database migrations
             run_migrations_on_startup=os.getenv(ENV_RUN_MIGRATIONS_ON_STARTUP, "true").lower() == "true",
             # Database connection pool
@@ -525,10 +507,6 @@ class HindsightConfig:
             reflect_provider = self.reflect_llm_provider or self.llm_provider
             reflect_model = self.reflect_llm_model or self.llm_model
             logger.info(f"LLM (reflect): provider={reflect_provider}, model={reflect_model}")
-        if self.consolidation_llm_provider or self.consolidation_llm_model:
-            consolidation_provider = self.consolidation_llm_provider or self.llm_provider
-            consolidation_model = self.consolidation_llm_model or self.llm_model
-            logger.info(f"LLM (consolidation): provider={consolidation_provider}, model={consolidation_model}")
         logger.info(f"Embeddings: provider={self.embeddings_provider}")
         logger.info(f"Reranker: provider={self.reranker_provider}")
         logger.info(f"Graph retriever: {self.graph_retriever}")

hindsight-api/hindsight_api/engine/consolidation/__init__.py

@@ -1,5 +0,0 @@
-"""Consolidation engine for automatic learning creation from memories."""
-
-from .consolidator import run_consolidation_job
-
-__all__ = ["run_consolidation_job"]

hindsight-api/hindsight_api/engine/consolidation/consolidator.py

@@ -1,859 +0,0 @@
-"""Consolidation engine for automatic observation creation from memories.
-
-The consolidation engine runs as a background job after retain operations complete.
-It processes new memories and either:
-- Creates new observations from novel facts
-- Updates existing observations when new evidence supports/contradicts/refines them
-
-Observations are stored in memory_units with fact_type='observation' and include:
-- proof_count: Number of supporting memories
-- source_memory_ids: Array of memory UUIDs that contribute to this observation
-- history: JSONB tracking changes over time
-"""
-
-import json
-import logging
-import time
-import uuid
-from datetime import datetime, timezone
-from typing import TYPE_CHECKING, Any
-
-from ..memory_engine import fq_table
-from ..retain import embedding_utils
-from .prompts import (
-    CONSOLIDATION_SYSTEM_PROMPT,
-    CONSOLIDATION_USER_PROMPT,
-)
-
-if TYPE_CHECKING:
-    from asyncpg import Connection
-
-    from ...api.http import RequestContext
-    from ..memory_engine import MemoryEngine
-
-logger = logging.getLogger(__name__)
-
-
-class ConsolidationPerfLog:
-    """Performance logging for consolidation operations."""
-
-    def __init__(self, bank_id: str):
-        self.bank_id = bank_id
-        self.start_time = time.time()
-        self.lines: list[str] = []
-        self.timings: dict[str, float] = {}
-
-    def log(self, message: str) -> None:
-        """Add a log line."""
-        self.lines.append(message)
-
-    def record_timing(self, key: str, duration: float) -> None:
-        """Record a timing measurement."""
-        if key in self.timings:
-            self.timings[key] += duration
-        else:
-            self.timings[key] = duration
-
-    def flush(self) -> None:
-        """Flush all log lines to the logger."""
-        total_time = time.time() - self.start_time
-        header = f"\n{'=' * 60}\nCONSOLIDATION for bank {self.bank_id}"
-        footer = f"{'=' * 60}\nCONSOLIDATION COMPLETE: {total_time:.3f}s total\n{'=' * 60}"
-
-        log_output = header + "\n" + "\n".join(self.lines) + "\n" + footer
-        logger.info(log_output)
-
-
-async def run_consolidation_job(
-    memory_engine: "MemoryEngine",
-    bank_id: str,
-    request_context: "RequestContext",
-) -> dict[str, Any]:
-    """
-    Run consolidation job for a bank.
-
-    This is called after retain operations to consolidate new memories into mental models.
-
-    Args:
-        memory_engine: MemoryEngine instance
-        bank_id: Bank identifier
-        request_context: Request context for authentication
-
-    Returns:
-        Dict with consolidation results
-    """
-    from ...config import get_config
-
-    config = get_config()
-    perf = ConsolidationPerfLog(bank_id)
-    max_memories_per_batch = config.consolidation_batch_size
-
-    # Check if consolidation is enabled
-    if not config.enable_observations:
-        logger.debug(f"Consolidation disabled for bank {bank_id}")
-        return {"status": "disabled", "bank_id": bank_id}
-
-    pool = memory_engine._pool
-
-    # Get bank profile
-    async with pool.acquire() as conn:
-        t0 = time.time()
-        bank_row = await conn.fetchrow(
-            f"""
-            SELECT bank_id, name, mission
-            FROM {fq_table("banks")}
-            WHERE bank_id = $1
-            """,
-            bank_id,
-        )
-
-        if not bank_row:
-            logger.warning(f"Bank {bank_id} not found for consolidation")
-            return {"status": "bank_not_found", "bank_id": bank_id}
-
-        mission = bank_row["mission"] or "General memory consolidation"
-        perf.record_timing("fetch_bank", time.time() - t0)
-
-        # Count total unconsolidated memories for progress logging
-        total_count = await conn.fetchval(
-            f"""
-            SELECT COUNT(*)
-            FROM {fq_table("memory_units")}
-            WHERE bank_id = $1
-              AND consolidated_at IS NULL
-              AND fact_type IN ('experience', 'world')
-            """,
-            bank_id,
-        )
-
-    if total_count == 0:
-        logger.debug(f"No new memories to consolidate for bank {bank_id}")
-        return {"status": "no_new_memories", "bank_id": bank_id, "memories_processed": 0}
-
-    logger.info(f"[CONSOLIDATION] bank={bank_id} total_unconsolidated={total_count}")
-    perf.log(f"[1] Found {total_count} pending memories to consolidate")
-
-    # Process each memory with individual commits for crash recovery
-    stats = {
-        "memories_processed": 0,
-        "observations_created": 0,
-        "observations_updated": 0,
-        "observations_merged": 0,
-        "actions_executed": 0,
-        "skipped": 0,
-    }
-
-    batch_num = 0
-    while True:
-        batch_num += 1
-        batch_start = time.time()
-
-        # Fetch next batch of unconsolidated memories
-        async with pool.acquire() as conn:
-            t0 = time.time()
-            memories = await conn.fetch(
-                f"""
-                SELECT id, text, fact_type, occurred_start, occurred_end, event_date, tags, mentioned_at
-                FROM {fq_table("memory_units")}
-                WHERE bank_id = $1
-                  AND consolidated_at IS NULL
-                  AND fact_type IN ('experience', 'world')
-                ORDER BY created_at ASC
-                LIMIT $2
-                """,
-                bank_id,
-                max_memories_per_batch,
-            )
-            perf.record_timing("fetch_memories", time.time() - t0)
-
-        if not memories:
-            break  # No more unconsolidated memories
-
-        for memory in memories:
-            mem_start = time.time()
-
-            # Process the memory (uses its own connection internally)
-            async with pool.acquire() as conn:
-                result = await _process_memory(
-                    conn=conn,
-                    memory_engine=memory_engine,
-                    bank_id=bank_id,
-                    memory=dict(memory),
-                    mission=mission,
-                    request_context=request_context,
-                    perf=perf,
-                )
-
-                # Mark memory as consolidated (committed immediately)
-                await conn.execute(
-                    f"""
-                    UPDATE {fq_table("memory_units")}
-                    SET consolidated_at = NOW()
-                    WHERE id = $1
-                    """,
-                    memory["id"],
-                )
-
-            mem_time = time.time() - mem_start
-            perf.record_timing("process_memory_total", mem_time)
-
-            stats["memories_processed"] += 1
-
-            action = result.get("action")
-            if action == "created":
-                stats["observations_created"] += 1
-                stats["actions_executed"] += 1
-            elif action == "updated":
-                stats["observations_updated"] += 1
-                stats["actions_executed"] += 1
-            elif action == "merged":
-                stats["observations_merged"] += 1
-                stats["actions_executed"] += 1
-            elif action == "multiple":
-                stats["observations_created"] += result.get("created", 0)
-                stats["observations_updated"] += result.get("updated", 0)
-                stats["observations_merged"] += result.get("merged", 0)
-                stats["actions_executed"] += result.get("total_actions", 0)
-            elif action == "skipped":
-                stats["skipped"] += 1
-
-            # Log progress periodically
-            if stats["memories_processed"] % 10 == 0:
-                logger.info(
-                    f"[CONSOLIDATION] bank={bank_id} progress: "
-                    f"{stats['memories_processed']}/{total_count} memories processed"
-                )
-
-        batch_time = time.time() - batch_start
-        perf.log(
-            f"[2] Batch {batch_num}: {len(memories)} memories in {batch_time:.3f}s "
-            f"(avg {batch_time / len(memories):.3f}s/memory)"
-        )
-
-    # Build summary
-    perf.log(
-        f"[3] Results: {stats['memories_processed']} memories -> "
-        f"{stats['actions_executed']} actions "
-        f"({stats['observations_created']} created, "
-        f"{stats['observations_updated']} updated, "
-        f"{stats['observations_merged']} merged, "
-        f"{stats['skipped']} skipped)"
-    )
-
-    # Add timing breakdown
-    timing_parts = []
-    if "recall" in perf.timings:
-        timing_parts.append(f"recall={perf.timings['recall']:.3f}s")
-    if "llm" in perf.timings:
-        timing_parts.append(f"llm={perf.timings['llm']:.3f}s")
-    if "embedding" in perf.timings:
-        timing_parts.append(f"embedding={perf.timings['embedding']:.3f}s")
-    if "db_write" in perf.timings:
-        timing_parts.append(f"db_write={perf.timings['db_write']:.3f}s")
-
-    if timing_parts:
-        perf.log(f"[4] Timing breakdown: {', '.join(timing_parts)}")
-
-    # Trigger mental model refreshes for models with refresh_after_consolidation=true
-    mental_models_refreshed = await _trigger_mental_model_refreshes(
-        memory_engine=memory_engine,
-        bank_id=bank_id,
-        request_context=request_context,
-        perf=perf,
-    )
-    stats["mental_models_refreshed"] = mental_models_refreshed
-
-    perf.flush()
-
-    return {"status": "completed", "bank_id": bank_id, **stats}
-
-
-async def _trigger_mental_model_refreshes(
-    memory_engine: "MemoryEngine",
-    bank_id: str,
-    request_context: "RequestContext",
-    perf: ConsolidationPerfLog | None = None,
-) -> int:
-    """
-    Trigger refreshes for mental models with refresh_after_consolidation=true.
-
-    Args:
-        memory_engine: MemoryEngine instance
-        bank_id: Bank identifier
-        request_context: Request context for authentication
-        perf: Performance logging
-
-    Returns:
-        Number of mental models scheduled for refresh
-    """
-    pool = memory_engine._pool
-
-    # Find mental models with refresh_after_consolidation=true
-    async with pool.acquire() as conn:
-        rows = await conn.fetch(
-            f"""
-            SELECT id, name
-            FROM {fq_table("mental_models")}
-            WHERE bank_id = $1
-              AND (trigger->>'refresh_after_consolidation')::boolean = true
-            """,
-            bank_id,
-        )
-
-    if not rows:
-        return 0
-
-    if perf:
-        perf.log(f"[5] Triggering refresh for {len(rows)} mental models with refresh_after_consolidation=true")
-
-    # Submit refresh tasks for each mental model
-    refreshed_count = 0
-    for row in rows:
-        mental_model_id = row["id"]
-        try:
-            await memory_engine.submit_async_refresh_mental_model(
-                bank_id=bank_id,
-                mental_model_id=mental_model_id,
-                request_context=request_context,
-            )
-            refreshed_count += 1
-            logger.info(
-                f"[CONSOLIDATION] Triggered refresh for mental model {mental_model_id} "
-                f"(name: {row['name']}) in bank {bank_id}"
-            )
-        except Exception as e:
-            logger.warning(f"[CONSOLIDATION] Failed to trigger refresh for mental model {mental_model_id}: {e}")
-
-    return refreshed_count
-
-
-async def _process_memory(
-    conn: "Connection",
-    memory_engine: "MemoryEngine",
-    bank_id: str,
-    memory: dict[str, Any],
-    mission: str,
-    request_context: "RequestContext",
-    perf: ConsolidationPerfLog | None = None,
-) -> dict[str, Any]:
-    """
-    Process a single memory for consolidation using a SINGLE LLM call.
-
-    This function:
-    1. Finds related observations (can be empty)
-    2. Uses ONE LLM call to extract durable knowledge AND decide on actions
-    3. Executes array of actions (can be multiple creates/updates)
-
-    The LLM handles all cases:
-    - No related observations: returns create action(s) with extracted durable knowledge
-    - Related observations exist: returns update/create actions based on tag routing
-    - Purely ephemeral fact: returns empty array (skip)
-
-    Returns:
-        Dict with action summary: created/updated/merged counts
-    """
-    fact_text = memory["text"]
-    memory_id = memory["id"]
-    fact_tags = memory.get("tags") or []
-
-    # Find related observations using the full recall system (NO tag filtering)
-    t0 = time.time()
-    related_observations = await _find_related_observations(
-        conn=conn,
-        memory_engine=memory_engine,
-        bank_id=bank_id,
-        query=fact_text,
-        request_context=request_context,
-    )
-    if perf:
-        perf.record_timing("recall", time.time() - t0)
-
-    # Single LLM call handles ALL cases (with or without existing observations)
-    # Note: Tags are NOT passed to LLM - they are handled algorithmically
-    t0 = time.time()
-    actions = await _consolidate_with_llm(
-        memory_engine=memory_engine,
-        fact_text=fact_text,
-        observations=related_observations,  # Can be empty list
-        mission=mission,
-    )
-    if perf:
-        perf.record_timing("llm", time.time() - t0)
-
-    if not actions:
-        # LLM returned empty array - fact is purely ephemeral, skip
-        return {"action": "skipped", "reason": "no_durable_knowledge"}
-
-    # Execute all actions and collect results
-    results = []
-    for action in actions:
-        action_type = action.get("action")
-        if action_type == "update":
-            result = await _execute_update_action(
-                conn=conn,
-                memory_engine=memory_engine,
-                bank_id=bank_id,
-                memory_id=memory_id,
-                action=action,
-                observations=related_observations,
-                source_fact_tags=fact_tags,  # Pass source fact's tags for security
-                source_occurred_start=memory.get("occurred_start"),
-                source_occurred_end=memory.get("occurred_end"),
-                source_mentioned_at=memory.get("mentioned_at"),
-                perf=perf,
-            )
-            results.append(result)
-        elif action_type == "create":
-            result = await _execute_create_action(
-                conn=conn,
-                memory_engine=memory_engine,
-                bank_id=bank_id,
-                memory_id=memory_id,
-                action=action,
-                source_fact_tags=fact_tags,  # Pass source fact's tags for security
-                event_date=memory.get("event_date"),
-                occurred_start=memory.get("occurred_start"),
-                occurred_end=memory.get("occurred_end"),
-                mentioned_at=memory.get("mentioned_at"),
-                perf=perf,
-            )
-            results.append(result)
-
-    if not results:
-        # No valid actions executed
-        return {"action": "skipped", "reason": "no_valid_actions"}
-
-    # Summarize results
-    created = sum(1 for r in results if r.get("action") == "created")
-    updated = sum(1 for r in results if r.get("action") == "updated")
-    merged = sum(1 for r in results if r.get("action") == "merged")
-
-    if len(results) == 1:
-        return results[0]
-
-    return {
-        "action": "multiple",
-        "created": created,
-        "updated": updated,
-        "merged": merged,
-        "total_actions": len(results),
-    }
-
-
-async def _execute_update_action(
-    conn: "Connection",
-    memory_engine: "MemoryEngine",
-    bank_id: str,
-    memory_id: uuid.UUID,
-    action: dict[str, Any],
-    observations: list[dict[str, Any]],
-    source_fact_tags: list[str] | None = None,
-    source_occurred_start: datetime | None = None,
-    source_occurred_end: datetime | None = None,
-    source_mentioned_at: datetime | None = None,
-    perf: ConsolidationPerfLog | None = None,
-) -> dict[str, Any]:
-    """
-    Execute an update action on an existing observation.
-
-    Updates the observation text, adds to history, increments proof_count,
-    and updates temporal fields:
-    - occurred_start: uses LEAST to keep the earliest start time
-    - occurred_end: uses GREATEST to keep the most recent end time
-    - mentioned_at: uses GREATEST to keep the most recent mention time
-
-    SECURITY: Merges source fact's tags into the observation's existing tags.
-    This ensures all contributors can see the observation they contributed to.
-    For example, if Lisa's observation (tags=['user_lisa']) is updated with
-    Mike's fact (tags=['user_mike']), the observation will have both tags.
-    """
-    learning_id = action.get("learning_id")
-    new_text = action.get("text")
-    reason = action.get("reason", "Updated with new fact")
-
-    if not learning_id or not new_text:
-        return {"action": "skipped", "reason": "missing_learning_id_or_text"}
-
-    # Find the observation
-    model = next((m for m in observations if str(m["id"]) == learning_id), None)
-    if not model:
-        return {"action": "skipped", "reason": "learning_not_found"}
-
-    # Build history entry
-    history = list(model.get("history", []))
-    history.append(
-        {
-            "previous_text": model["text"],
-            "changed_at": datetime.now(timezone.utc).isoformat(),
-            "reason": reason,
-            "source_memory_id": str(memory_id),
-        }
-    )
-
-    # Update source_memory_ids
-    source_ids = list(model.get("source_memory_ids", []))
-    source_ids.append(memory_id)
-
-    # SECURITY: Merge source fact's tags into existing observation tags
-    # This ensures all contributors can see the observation they contributed to
-    existing_tags = set(model.get("tags", []) or [])
-    source_tags = set(source_fact_tags or [])
-    merged_tags = list(existing_tags | source_tags)  # Union of both tag sets
-    if source_tags and source_tags != existing_tags:
-        logger.debug(
-            f"Security: Merging tags for observation {learning_id}: "
-            f"existing={list(existing_tags)}, source={list(source_tags)}, merged={merged_tags}"
-        )
-
-    # Generate new embedding for updated text
-    t0 = time.time()
-    embeddings = await embedding_utils.generate_embeddings_batch(memory_engine.embeddings, [new_text])
-    embedding_str = str(embeddings[0]) if embeddings else None
-    if perf:
-        perf.record_timing("embedding", time.time() - t0)
-
-    # Update the observation
-    # - occurred_start: LEAST keeps the earliest start time across all source facts
-    # - occurred_end: GREATEST keeps the most recent end time across all source facts
-    # - mentioned_at: GREATEST keeps the most recent mention time
-    # - tags: merged from existing + source fact (for visibility)
-    t0 = time.time()
-    await conn.execute(
-        f"""
-        UPDATE {fq_table("memory_units")}
-        SET text = $1,
-            embedding = $2::vector,
-            history = $3,
-            source_memory_ids = $4,
-            proof_count = $5,
-            tags = $10,
-            updated_at = now(),
-            occurred_start = LEAST(occurred_start, COALESCE($7, occurred_start)),
-            occurred_end = GREATEST(occurred_end, COALESCE($8, occurred_end)),
-            mentioned_at = GREATEST(mentioned_at, COALESCE($9, mentioned_at))
-        WHERE id = $6
-        """,
-        new_text,
-        embedding_str,
-        json.dumps(history),
-        source_ids,
-        len(source_ids),
-        uuid.UUID(learning_id),
-        source_occurred_start,
-        source_occurred_end,
-        source_mentioned_at,
-        merged_tags,
-    )
-
-    # Create links from memory to observation
-    await _create_memory_links(conn, memory_id, uuid.UUID(learning_id))
-    if perf:
-        perf.record_timing("db_write", time.time() - t0)
-
-    logger.debug(f"Updated observation {learning_id} with memory {memory_id}")
-
-    return {"action": "updated", "observation_id": learning_id}
-
-
-async def _execute_create_action(
-    conn: "Connection",
-    memory_engine: "MemoryEngine",
-    bank_id: str,
-    memory_id: uuid.UUID,
-    action: dict[str, Any],
-    source_fact_tags: list[str] | None = None,
-    event_date: datetime | None = None,
-    occurred_start: datetime | None = None,
-    occurred_end: datetime | None = None,
-    mentioned_at: datetime | None = None,
-    perf: ConsolidationPerfLog | None = None,
-) -> dict[str, Any]:
-    """
-    Execute a create action for a new observation.
-
-    Creates a new observation with the specified text.
-    The text comes directly from the classify LLM - no second LLM call needed.
-
-    Tags are determined algorithmically (not by LLM):
-    - Observations always inherit their source fact's tags
-    - This ensures visibility scope is maintained (security)
-    """
-    text = action.get("text")
-
-    # Tags are determined algorithmically - always use source fact's tags
-    # This ensures private memories create private observations
-    tags = source_fact_tags or []
-
-    if not text:
-        return {"action": "skipped", "reason": "missing_text"}
-
-    # Use text directly from classify - skip the redundant LLM call
-    result = await _create_observation_directly(
-        conn=conn,
-        memory_engine=memory_engine,
-        bank_id=bank_id,
-        source_memory_id=memory_id,
-        observation_text=text,  # Text already processed by classify LLM
-        tags=tags,
-        event_date=event_date,
-        occurred_start=occurred_start,
-        occurred_end=occurred_end,
-        mentioned_at=mentioned_at,
-        perf=perf,
-    )
-
-    logger.debug(f"Created observation {result.get('observation_id')} from memory {memory_id} (tags: {tags})")
-
-    return result
-
-
-async def _create_memory_links(
-    conn: "Connection",
-    memory_id: uuid.UUID,
-    observation_id: uuid.UUID,
-) -> None:
-    """
-    Placeholder for observation link creation.
-
-    Observations do NOT get any memory_links copied from their source facts.
-    Instead, retrieval uses source_memory_ids to traverse:
-    - Entity connections: observation → source_memory_ids → unit_entities
-    - Semantic similarity: observations have their own embeddings
-    - Temporal proximity: observations have their own temporal fields
-
-    This avoids data duplication and ensures observations are always
-    connected via their source facts' relationships.
-
-    The memory_id and observation_id parameters are kept for interface
-    compatibility but no links are created.
-    """
-    # No links are created - observations rely on source_memory_ids for traversal
-    pass
-
-
-async def _find_related_observations(
-    conn: "Connection",
-    memory_engine: "MemoryEngine",
-    bank_id: str,
-    query: str,
-    request_context: "RequestContext",
-) -> list[dict[str, Any]]:
-    """
-    Find observations related to the given query using the full recall system.
-
-    IMPORTANT: We do NOT filter by tags here. Consolidation needs to see ALL
-    potentially related observations regardless of scope, so the LLM can
-    decide on tag routing (same scope update vs cross-scope create).
-
-    This leverages:
-    - Semantic search (embedding similarity)
-    - BM25 text search (keyword matching)
-    - Entity-based retrieval (shared entities)
-    - Graph traversal (connected via entity links)
-
-    Returns:
-        List of related observations with their tags for LLM tag routing
-    """
-    # Use recall to find related observations
-    # NO tags parameter - we want ALL observations regardless of scope
-    # Use low max_tokens since we only need observations, not memories
-    recall_result = await memory_engine.recall_async(
-        bank_id=bank_id,
-        query=query,
-        max_tokens=5000,  # Token budget for observations
-        fact_type=["observation"],  # Only retrieve observations
-        request_context=request_context,
-        _quiet=True,  # Suppress logging
-        # NO tags parameter - intentionally get ALL observations
-    )
-
-    # If no observations returned, return empty list
-    # When fact_type=["observation"], results come back in `results` field
-    if not recall_result.results:
-        return []
-
-    # Trust recall's relevance filtering - fetch full data for each observation
-    results = []
-    for obs in recall_result.results:
-        # Fetch full observation data from DB to get history, source_memory_ids, tags
-        row = await conn.fetchrow(
-            f"""
-            SELECT id, text, proof_count, history, tags, source_memory_ids, created_at, updated_at
-            FROM {fq_table("memory_units")}
-            WHERE id = $1 AND bank_id = $2 AND fact_type = 'observation'
-            """,
-            uuid.UUID(obs.id),
-            bank_id,
-        )
-
-        if row:
-            history = row["history"]
-            if isinstance(history, str):
-                history = json.loads(history)
-            elif history is None:
-                history = []
-
-            results.append(
-                {
-                    "id": row["id"],
-                    "text": row["text"],
-                    "proof_count": row["proof_count"] or 1,
-                    "history": history,
-                    "tags": row["tags"] or [],  # Include tags for LLM tag routing
-                    "source_memory_ids": row["source_memory_ids"] or [],
-                    "similarity": 1.0,  # Retrieved via recall so assumed relevant
-                }
-            )
-
-    return results
-
-
-async def _consolidate_with_llm(
-    memory_engine: "MemoryEngine",
-    fact_text: str,
-    observations: list[dict[str, Any]],
-    mission: str,
-) -> list[dict[str, Any]]:
-    """
-    Single LLM call to extract durable knowledge and decide on consolidation actions.
-
-    This handles ALL cases:
-    - No related observations: extracts durable knowledge, returns create action
-    - Related observations exist: compares and returns update/create actions
-    - Purely ephemeral fact: returns empty array
-
-    Note: Tags are NOT handled by the LLM. They are determined algorithmically:
-    - CREATE: observation inherits source fact's tags
-    - UPDATE: observation merges source fact's tags with existing tags
-
-    Returns:
-        List of actions, each being:
-        - {"action": "update", "learning_id": "uuid", "text": "...", "reason": "..."}
-        - {"action": "create", "text": "...", "reason": "..."}
-        - [] if fact is purely ephemeral (no durable knowledge)
-    """
-    # Format observations WITH their tags (or "None" if empty)
-    if observations:
-        observations_text = "\n".join(
-            f'- ID: {obs["id"]}, Tags: {json.dumps(obs["tags"])}, Text: "{obs["text"]}" (proof_count: {obs["proof_count"]})'
-            for obs in observations
-        )
-    else:
-        observations_text = "None (this is a new topic - create if fact contains durable knowledge)"
-
-    # Only include mission section if mission is set and not the default
-    mission_section = ""
-    if mission and mission != "General memory consolidation":
-        mission_section = f"""
-MISSION CONTEXT: {mission}
-
-Focus on DURABLE knowledge that serves this mission, not ephemeral state.
-"""
-
-    user_prompt = CONSOLIDATION_USER_PROMPT.format(
-        mission_section=mission_section,
-        fact_text=fact_text,
-        observations_text=observations_text,
-    )
-
-    messages = [
-        {"role": "system", "content": CONSOLIDATION_SYSTEM_PROMPT},
-        {"role": "user", "content": user_prompt},
-    ]
-
-    try:
-        result = await memory_engine._consolidation_llm_config.call(
-            messages=messages,
-            skip_validation=True,  # Raw JSON response
-            scope="consolidation",
-        )
-        # Parse JSON response - should be an array
-        if isinstance(result, str):
-            result = json.loads(result)
-        # Ensure result is a list
-        if isinstance(result, list):
-            return result
-        # Handle legacy single-action format for backward compatibility
-        if isinstance(result, dict):
-            if result.get("related_ids") and result.get("consolidated_text"):
-                # Convert old format to new format
-                return [
-                    {
-                        "action": "update",
-                        "learning_id": result["related_ids"][0],
-                        "text": result["consolidated_text"],
-                        "reason": result.get("reason", ""),
-                    }
-                ]
-            return []
-        return []
-    except Exception as e:
-        logger.warning(f"Error in consolidation LLM call: {e}")
-        return []
-
-
-async def _create_observation_directly(
-    conn: "Connection",
-    memory_engine: "MemoryEngine",
-    bank_id: str,
-    source_memory_id: uuid.UUID,
-    observation_text: str,
-    tags: list[str] | None = None,
-    event_date: datetime | None = None,
-    occurred_start: datetime | None = None,
-    occurred_end: datetime | None = None,
-    mentioned_at: datetime | None = None,
-    perf: ConsolidationPerfLog | None = None,
-) -> dict[str, Any]:
-    """
-    Create an observation directly with pre-processed text (no LLM call).
-
-    Used when the classify LLM has already provided the learning text.
-    This avoids the redundant second LLM call.
-    """
-    # Generate embedding for the observation (convert to string for pgvector)
-    t0 = time.time()
-    embeddings = await embedding_utils.generate_embeddings_batch(memory_engine.embeddings, [observation_text])
-    embedding_str = str(embeddings[0]) if embeddings else None
-    if perf:
-        perf.record_timing("embedding", time.time() - t0)
-
-    # Create the observation as a memory_unit
-    now = datetime.now(timezone.utc)
-    obs_event_date = event_date or now
-    obs_occurred_start = occurred_start or now
-    obs_occurred_end = occurred_end or now
-    obs_mentioned_at = mentioned_at or now
-    obs_tags = tags or []
-
-    t0 = time.time()
-    observation_id = uuid.uuid4()
-    row = await conn.fetchrow(
-        f"""
-        INSERT INTO {fq_table("memory_units")} (
-            id, bank_id, text, fact_type, embedding, proof_count, source_memory_ids, history,
-            tags, event_date, occurred_start, occurred_end, mentioned_at
-        )
-        VALUES ($1, $2, $3, 'observation', $4::vector, 1, $5, '[]'::jsonb, $6, $7, $8, $9, $10)
-        RETURNING id
-        """,
-        observation_id,
-        bank_id,
-        observation_text,
-        embedding_str,
-        [source_memory_id],
-        obs_tags,
-        obs_event_date,
-        obs_occurred_start,
-        obs_occurred_end,
-        obs_mentioned_at,
-    )
-
-    # Create links between memory and observation (includes entity links, memory_links)
-    await _create_memory_links(conn, source_memory_id, observation_id)
-    if perf:
-        perf.record_timing("db_write", time.time() - t0)
-
-    logger.debug(f"Created observation {observation_id} from memory {source_memory_id} (tags: {obs_tags})")
-
-    return {"action": "created", "observation_id": str(row["id"]), "tags": obs_tags}

hindsight-api/hindsight_api/engine/consolidation/prompts.py

@@ -1,69 +0,0 @@
-"""Prompts for the consolidation engine."""
-
-CONSOLIDATION_SYSTEM_PROMPT = """You are a memory consolidation system. Your job is to convert facts into durable knowledge (observations) and merge with existing knowledge when appropriate.
-
-You must output ONLY valid JSON with no markdown formatting, no code blocks, and no additional text.
-
-## EXTRACT DURABLE KNOWLEDGE, NOT EPHEMERAL STATE
-Facts often describe events or actions. Extract the DURABLE KNOWLEDGE implied by the fact, not the transient state.
-
-Examples of extracting durable knowledge:
-- "User moved to Room 203" -> "Room 203 exists" (location exists, not where user is now)
-- "User visited Acme Corp at Room 105" -> "Acme Corp is located in Room 105"
-- "User took the elevator to floor 3" -> "Floor 3 is accessible by elevator"
-- "User met Sarah at the lobby" -> "Sarah can be found at the lobby"
-
-DO NOT track current user position/state as knowledge - that changes constantly.
-DO track permanent facts learned from the user's actions.
-
-## PRESERVE SPECIFIC DETAILS
-Keep names, locations, numbers, and other specifics. Do NOT:
-- Abstract into general principles
-- Generate business insights
-- Make knowledge generic
-
-GOOD examples:
-- Fact: "John likes pizza" -> "John likes pizza"
-- Fact: "Alice works at Google" -> "Alice works at Google"
-
-BAD examples:
-- "John likes pizza" -> "Understanding dietary preferences helps..." (TOO ABSTRACT)
-- "User is at Room 203" -> "User is currently at Room 203" (EPHEMERAL STATE)
-
-## MERGE RULES (when comparing to existing observations):
-1. REDUNDANT: Same information worded differently → update existing
-2. CONTRADICTION: Opposite information about same topic → update with history (e.g., "used to X, now Y")
-3. UPDATE: New state replacing old state → update with history
-
-## CRITICAL RULES:
-- NEVER merge facts about DIFFERENT people
-- NEVER merge unrelated topics (food preferences vs work vs hobbies)
-- When merging contradictions, capture the CHANGE (before → after)
-- Keep observations focused on ONE specific topic per person
-- The "text" field MUST contain durable knowledge, not ephemeral state
-- Do NOT include "tags" in output - tags are handled automatically"""
-
-CONSOLIDATION_USER_PROMPT = """Analyze this new fact and consolidate into knowledge.
-{mission_section}
-NEW FACT: {fact_text}
-
-EXISTING OBSERVATIONS:
-{observations_text}
-
-Instructions:
-1. First, extract the DURABLE KNOWLEDGE from the fact (not ephemeral state like "user is at X")
-2. Then compare with existing observations:
-   - If an observation covers the same topic: UPDATE it with the new knowledge
-   - If no observation covers the topic: CREATE a new one
-
-Output JSON array of actions (ALWAYS an array, even for single action):
-[
-  {{"action": "update", "learning_id": "uuid", "text": "updated durable knowledge", "reason": "..."}},
-  {{"action": "create", "text": "new durable knowledge", "reason": "..."}}
-]
-
-If NO consolidation is needed (fact is purely ephemeral with no durable knowledge):
-[]
-
-If no observations exist and fact contains durable knowledge:
-[{{"action": "create", "text": "durable knowledge text", "reason": "new topic"}}]"""

hindsight-api/hindsight_api/engine/cross_encoder.py

@@ -132,25 +132,36 @@ class LocalSTCrossEncoder(CrossEncoderModel):
 
         logger.info(f"Reranker: initializing local provider with model {self.model_name}")
 
-        # Determine device based on hardware availability.
-        # We always set low_cpu_mem_usage=False to prevent lazy loading (meta tensors)
-        # which can cause issues when accelerate is installed but no GPU is available.
-        # Note: We do NOT use device_map because CrossEncoder internally calls .to(device)
-        # after loading, which conflicts with accelerate's device_map handling.
+        # Determine device and device_map based on hardware and installed packages.
+        # When accelerate is installed but no GPU/MPS is available, transformers can
+        # incorrectly use lazy loading (meta tensors) which fails on .to(device).
+        # We use device_map="cpu" in that case to force direct CPU loading.
         import torch
 
+        try:
+            import accelerate  # type: ignore[import-not-found]  # noqa: F401
+
+            accelerate_available = True
+        except ImportError:
+            accelerate_available = False
+
         # Check for GPU (CUDA) or Apple Silicon (MPS)
         has_gpu = torch.cuda.is_available() or (hasattr(torch.backends, "mps") and torch.backends.mps.is_available())
 
         if has_gpu:
             device = None  # Let sentence-transformers auto-detect GPU/MPS
+            device_map = None
+        elif accelerate_available:
+            device = "cpu"
+            device_map = "cpu"  # Force direct CPU loading to avoid meta tensors
         else:
             device = "cpu"
+            device_map = None
 
         self._model = CrossEncoder(
             self.model_name,
             device=device,
-            model_kwargs={"low_cpu_mem_usage": False},
+            model_kwargs={"low_cpu_mem_usage": False, "device_map": device_map},
         )
 
         # Initialize shared executor (limited workers naturally limits concurrency)

hindsight-api/hindsight_api/engine/directives/__init__.py

@@ -1,5 +0,0 @@
-"""Directives module for hard rules injected into prompts."""
-
-from .models import Directive
-
-__all__ = ["Directive"]

hindsight-api/hindsight_api/engine/directives/models.py

@@ -1,37 +0,0 @@
-"""Pydantic models for directives."""
-
-from datetime import datetime, timezone
-from uuid import UUID
-
-from pydantic import BaseModel, Field
-
-
-class Directive(BaseModel):
-    """A directive is a hard rule injected into prompts.
-
-    Directives are user-defined rules that guide agent behavior. Unlike mental models
-    which are automatically consolidated from memories, directives are explicit
-    instructions that are always included in relevant prompts.
-
-    Examples:
-    - "Always respond in formal English"
-    - "Never share personal data with third parties"
-    - "Prefer conservative investment recommendations"
-    """
-
-    id: UUID = Field(description="Unique identifier")
-    bank_id: str = Field(description="Bank this directive belongs to")
-    name: str = Field(description="Human-readable name")
-    content: str = Field(description="The directive text to inject into prompts")
-    priority: int = Field(default=0, description="Higher priority directives are injected first")
-    is_active: bool = Field(default=True, description="Whether this directive is currently active")
-    tags: list[str] = Field(default_factory=list, description="Tags for filtering")
-    created_at: datetime = Field(
-        default_factory=lambda: datetime.now(timezone.utc), description="When this directive was created"
-    )
-    updated_at: datetime = Field(
-        default_factory=lambda: datetime.now(timezone.utc), description="When this directive was last updated"
-    )
-
-    class Config:
-        from_attributes = True

hindsight-api/hindsight_api/engine/embeddings.py

@@ -129,23 +129,36 @@ class LocalSTEmbeddings(Embeddings):
 
         logger.info(f"Embeddings: initializing local provider with model {self.model_name}")
 
-        # Determine device based on hardware availability.
-        # We always set low_cpu_mem_usage=False to prevent lazy loading (meta tensors)
-        # which can cause issues when accelerate is installed but no GPU is available.
+        # Determine device and device_map based on hardware and installed packages.
+        # When accelerate is installed but no GPU/MPS is available, transformers can
+        # incorrectly use lazy loading (meta tensors) which fails on .to(device).
+        # We use device_map="cpu" in that case to force direct CPU loading.
         import torch
 
+        try:
+            import accelerate  # type: ignore[import-not-found]  # noqa: F401
+
+            accelerate_available = True
+        except ImportError:
+            accelerate_available = False
+
         # Check for GPU (CUDA) or Apple Silicon (MPS)
         has_gpu = torch.cuda.is_available() or (hasattr(torch.backends, "mps") and torch.backends.mps.is_available())
 
         if has_gpu:
             device = None  # Let sentence-transformers auto-detect GPU/MPS
+            device_map = None
+        elif accelerate_available:
+            device = "cpu"
+            device_map = "cpu"  # Force direct CPU loading to avoid meta tensors
         else:
             device = "cpu"
+            device_map = None
 
         self._model = SentenceTransformer(
             self.model_name,
             device=device,
-            model_kwargs={"low_cpu_mem_usage": False},
+            model_kwargs={"low_cpu_mem_usage": False, "device_map": device_map},
         )
 
         self._dimension = self._model.get_sentence_embedding_dimension()

hindsight-api/hindsight_api/engine/llm_wrapper.py

@@ -647,13 +647,7 @@ class LLMProvider:
                         success=True,
                     )
 
-                    return LLMToolCallResult(
-                        content=content,
-                        tool_calls=tool_calls,
-                        finish_reason=finish_reason,
-                        input_tokens=input_tokens,
-                        output_tokens=output_tokens,
-                    )
+                    return LLMToolCallResult(content=content, tool_calls=tool_calls, finish_reason=finish_reason)
 
                 except APIConnectionError as e:
                     last_exception = e
@@ -803,10 +797,6 @@ class LLMProvider:
                 content = "".join(content_parts) if content_parts else None
                 finish_reason = "tool_calls" if tool_calls else "stop"
 
-                # Extract token usage
-                input_tokens = response.usage.input_tokens or 0
-                output_tokens = response.usage.output_tokens or 0
-
                 # Record metrics
                 metrics = get_metrics_collector()
                 metrics.record_llm_call(
@@ -814,18 +804,12 @@ class LLMProvider:
                     model=self.model,
                     scope=scope,
                     duration=time.time() - start_time,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
+                    input_tokens=response.usage.input_tokens or 0,
+                    output_tokens=response.usage.output_tokens or 0,
                     success=True,
                 )
 
-                return LLMToolCallResult(
-                    content=content,
-                    tool_calls=tool_calls,
-                    finish_reason=finish_reason,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                )
+                return LLMToolCallResult(content=content, tool_calls=tool_calls, finish_reason=finish_reason)
 
             except (APIConnectionError, APIStatusError) as e:
                 if isinstance(e, APIStatusError) and e.status_code in (401, 403):
@@ -946,13 +930,7 @@ class LLMProvider:
                     success=True,
                 )
 
-                return LLMToolCallResult(
-                    content=content,
-                    tool_calls=tool_calls,
-                    finish_reason=finish_reason,
-                    input_tokens=input_tokens,
-                    output_tokens=output_tokens,
-                )
+                return LLMToolCallResult(content=content, tool_calls=tool_calls, finish_reason=finish_reason)
 
             except genai_errors.APIError as e:
                 if e.code in (401, 403):

hindsight-api/hindsight_api/engine/mental_models/__init__.py

@@ -1,12 +1,16 @@
 """
 Mental models module for Hindsight.
 
-Mental models contain directives - hard rules that are injected into reflect prompts.
-Directives are user-defined and their observations are user-provided (not LLM-generated).
+Mental models are synthesized summaries that represent understanding. They come
+in different subtypes based on how they were created:
 
-Other types of consolidated knowledge are handled by:
-- Learnings: Automatic bottom-up consolidation from facts
-- Pinned Reflections: User-curated living documents
+- Structural: Derived from the bank's mission (e.g., "Be a PM for engineering team")
+  These are created upfront based on what any agent with this role would need.
+
+- Emergent: Discovered from data patterns (named entities, temporal clusters, etc.)
+  These surface organically as facts are retained.
+
+- Pinned: User-defined models that persist across refreshes.
 """
 
 from .models import MentalModel, MentalModelSubtype

hindsight-api/hindsight_api/engine/mental_models/emergent.py

@@ -0,0 +1,311 @@
+"""
+Emergent mental model detection and promotion.
+
+Emergent models are discovered from data patterns:
+- Named entity extraction (people, projects, systems)
+- Temporal clustering (events with multiple references)
+- Causal patterns ("Because X, we do Y")
+- Behavioral anchors ("After X, we started Y")
+- Reference frequency (anything mentioned repeatedly)
+
+When a pattern is detected, it goes through a mission filter to check relevance,
+and if relevant, is promoted to a mental model.
+"""
+
+import logging
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from .models import EmergentCandidate
+
+if TYPE_CHECKING:
+    from ..llm_wrapper import LLMConfig
+
+logger = logging.getLogger(__name__)
+
+
+class MissionFilterCandidate(BaseModel):
+    """Result of mission filtering for a single candidate."""
+
+    name: str
+    promote: bool = Field(description="True if this is a specific named entity worth tracking")
+    reason: str = Field(description="Brief explanation for the decision")
+
+
+class MissionFilterResponse(BaseModel):
+    """Response from LLM for mission filtering."""
+
+    candidates: list[MissionFilterCandidate] = Field(description="Filtering decision for each candidate")
+
+
+def build_mission_filter_prompt(mission: str, candidates: list[EmergentCandidate]) -> str:
+    """Build the prompt for filtering candidates by mission relevance."""
+    candidate_list = "\n".join(
+        [f"- {c.name} (mentions: {c.mention_count}, method: {c.detection_method})" for c in candidates]
+    )
+
+    return f"""Filter these detected entities. For each one, decide: promote=true or promote=false.
+
+MISSION: {mission}
+
+DETECTED ENTITIES:
+{candidate_list}
+
+=== DECISION RULES ===
+
+Set promote=true ONLY for specific, named entities:
+- Person names: "John", "Maria", "Alice Chen", "Dr. Smith"
+- Named organizations: "Google", "Acme Corp", "Frontend Team"
+- Named places: "Central Park Zoo", "NYC Office", "Building A"
+- Named projects: "Project Phoenix", "Auth Service v2"
+
+Set promote=false for EVERYTHING ELSE, including:
+- Common English words: user, support, help, family, kids, parents, friends, people, team, photo, nature, park, office, home, work, school, joy, love, hope, fear, anger, gratitude, kindness, passion, motivation, inspiration, encouragement, positivity, energy, community, connection, commitment, collaboration, growth, impact, difference, success, progress, change, education, volunteering, veterans, homeless, shelter, meeting, project, system, process, event
+- Generic categories (even capitalized): Users, Customers, Team, Family, Kids, Veterans, Community
+- Abstract concepts: motivation, inspiration, gratitude, commitment, resilience
+
+THE TEST: Is this a specific name you'd find in a contact list or org chart?
+- "John" → YES (promote=true)
+- "kids" → NO (promote=false)
+- "community" → NO (promote=false)
+- "Maria" → YES (promote=true)
+- "park" → NO (promote=false)
+
+When in doubt, set promote=false."""
+
+
+def get_mission_filter_system_message() -> str:
+    """System message for mission filtering."""
+    return """You filter entities for promotion. Output JSON with 'candidates' array.
+
+Rules:
+- promote=true ONLY for specific names (people, organizations, named places/projects)
+- promote=false for common words, generic categories, abstract concepts
+
+Examples:
+- "John" → promote=true (person name)
+- "kids" → promote=false (generic category)
+- "community" → promote=false (abstract concept)
+- "Google" → promote=true (organization name)
+- "motivation" → promote=false (abstract concept)
+
+When in doubt, promote=false. Most entities should be rejected."""
+
+
+async def filter_candidates_by_mission(
+    llm_config: "LLMConfig",
+    mission: str,
+    candidates: list[EmergentCandidate],
+) -> list[EmergentCandidate]:
+    """
+    Filter emergent candidates to keep only specific, named entities.
+
+    Args:
+        llm_config: LLM configuration
+        mission: The bank's mission (used for context)
+        candidates: List of detected candidates
+
+    Returns:
+        Filtered list of candidates that are specific named entities
+    """
+    if not candidates:
+        return []
+
+    if not mission:
+        # No mission = no filtering, keep all candidates
+        logger.debug("[EMERGENT] No mission set, skipping filter")
+        return candidates
+
+    prompt = build_mission_filter_prompt(mission, candidates)
+
+    try:
+        result = await llm_config.call(
+            messages=[
+                {"role": "system", "content": get_mission_filter_system_message()},
+                {"role": "user", "content": prompt},
+            ],
+            response_format=MissionFilterResponse,
+            scope="mental_model_mission_filter",
+        )
+
+        # Build name -> promote map
+        promote_map = {c.name: c.promote for c in result.candidates}
+
+        # Filter candidates
+        filtered = []
+        for candidate in candidates:
+            if candidate.name in promote_map:
+                if promote_map[candidate.name]:
+                    filtered.append(candidate)
+                    logger.debug(f"[EMERGENT] Promoting '{candidate.name}'")
+                else:
+                    logger.debug(f"[EMERGENT] Rejecting '{candidate.name}'")
+            else:
+                # Candidate not in response - reject by default
+                logger.debug(f"[EMERGENT] '{candidate.name}' not in response, rejecting")
+
+        logger.info(f"[EMERGENT] Mission filter: {len(filtered)}/{len(candidates)} candidates promoted")
+        return filtered
+
+    except Exception as e:
+        logger.warning(f"[EMERGENT] Mission filter failed, rejecting all candidates: {e}")
+        return []
+
+
+async def evaluate_emergent_models(
+    llm_config: "LLMConfig",
+    models: list[dict],
+) -> list[str]:
+    """
+    Evaluate existing emergent models to check if they should be kept.
+
+    This re-evaluates emergent models using the same filtering criteria
+    as new candidates. Models that are generic/abstract will be removed.
+
+    Args:
+        llm_config: LLM configuration
+        models: List of existing emergent model dicts with 'name', 'id'
+
+    Returns:
+        List of model IDs that should be REMOVED (no longer valid)
+    """
+    if not models:
+        return []
+
+    # Convert existing models to candidates for evaluation
+    candidates = [
+        EmergentCandidate(
+            name=m["name"],
+            detection_method="existing_emergent_model",
+            mention_count=0,
+        )
+        for m in models
+    ]
+
+    # Build a simple prompt for re-evaluation
+    names_list = "\n".join([f"- {m['name']}" for m in models])
+    prompt = f"""Re-evaluate these existing mental models. For each one, decide: promote=true (keep) or promote=false (remove).
+
+EXISTING MODELS:
+{names_list}
+
+=== DECISION RULES ===
+
+Set promote=true ONLY for specific, named entities:
+- Person names: "John", "Maria", "Alice Chen", "Dr. Smith"
+- Named organizations: "Google", "Acme Corp", "Frontend Team"
+- Named places: "Central Park Zoo", "NYC Office", "Building A"
+- Named projects: "Project Phoenix", "Auth Service v2"
+
+Set promote=false for EVERYTHING ELSE, including:
+- Common English words: user, support, help, family, kids, parents, friends, people, team, photo, nature, park, office, home, work, school, joy, love, hope, fear, anger, gratitude, kindness, passion, motivation, inspiration, encouragement, positivity, energy, community, connection, commitment, collaboration, growth, impact, difference, success, progress, change, education, volunteering, veterans, homeless, shelter, meeting, project, system, process, event
+- Generic categories (even capitalized): Users, Customers, Team, Family, Kids, Veterans, Community
+- Abstract concepts: motivation, inspiration, gratitude, commitment, resilience
+
+THE TEST: Is this a specific name you'd find in a contact list or org chart?
+- "John" → YES (promote=true)
+- "kids" → NO (promote=false)
+- "community" → NO (promote=false)
+
+When in doubt, set promote=false."""
+
+    try:
+        result = await llm_config.call(
+            messages=[
+                {"role": "system", "content": get_mission_filter_system_message()},
+                {"role": "user", "content": prompt},
+            ],
+            response_format=MissionFilterResponse,
+            scope="mental_model_emergent_evaluation",
+        )
+
+        # Build name -> promote map
+        promote_map = {c.name: c.promote for c in result.candidates}
+
+        # Find models to remove
+        models_to_remove = []
+        for model in models:
+            name = model["name"]
+            if name in promote_map:
+                if not promote_map[name]:
+                    models_to_remove.append(model["id"])
+                else:
+                    logger.debug(f"[EMERGENT] Keeping '{name}'")
+            else:
+                # Model not in response - remove to be safe
+                logger.info(f"[EMERGENT] '{name}' not in evaluation response, marking for removal")
+                models_to_remove.append(model["id"])
+
+        logger.info(f"[EMERGENT] Evaluation: {len(models_to_remove)}/{len(models)} emergent models marked for removal")
+        return models_to_remove
+
+    except Exception as e:
+        logger.warning(f"[EMERGENT] Evaluation failed, keeping all models: {e}")
+        return []
+
+
+async def detect_entity_candidates(
+    pool,
+    bank_id: str,
+    min_mentions: int = 5,
+    top_percent: int = 20,
+) -> list[EmergentCandidate]:
+    """
+    Detect entities that are candidates for promotion to mental models.
+
+    Args:
+        pool: Database connection pool
+        bank_id: Bank identifier
+        min_mentions: Minimum mention count to consider
+        top_percent: Only consider top X% by mention count
+
+    Returns:
+        List of entity candidates
+    """
+    from ..db_utils import acquire_with_retry
+    from ..memory_engine import fq_table
+
+    candidates = []
+
+    async with acquire_with_retry(pool) as conn:
+        # Get entities that meet criteria and don't already have mental models
+        rows = await conn.fetch(
+            f"""
+            WITH ranked AS (
+                SELECT
+                    e.id,
+                    e.canonical_name,
+                    e.mention_count,
+                    PERCENT_RANK() OVER (ORDER BY e.mention_count DESC) as rank_pct
+                FROM {fq_table("entities")} e
+                LEFT JOIN {fq_table("mental_models")} mm
+                    ON mm.entity_id = e.id AND mm.bank_id = e.bank_id
+                WHERE e.bank_id = $1
+                  AND e.mention_count >= $2
+                  AND mm.id IS NULL  -- Not already a mental model
+            )
+            SELECT id, canonical_name, mention_count
+            FROM ranked
+            WHERE rank_pct <= $3
+            ORDER BY mention_count DESC
+            LIMIT 50
+            """,
+            bank_id,
+            min_mentions,
+            top_percent / 100.0,
+        )
+
+        for row in rows:
+            candidates.append(
+                EmergentCandidate(
+                    name=row["canonical_name"],
+                    detection_method="named_entity_extraction",
+                    mention_count=row["mention_count"],
+                    entity_id=str(row["id"]),
+                    relevance_score=0.0,
+                )
+            )
+
+    logger.debug(f"[EMERGENT] Detected {len(candidates)} entity candidates")
+    return candidates

hindsight-api/hindsight_api/engine/mental_models/models.py

@@ -9,14 +9,12 @@ from pydantic import BaseModel, Field
 
 
 class MentalModelSubtype(str, Enum):
-    """Subtype of mental model.
-
-    Currently only DIRECTIVE is supported. Other types of consolidated knowledge
-    are handled by:
-    - Learnings: Automatic bottom-up consolidation from facts
-    - Pinned Reflections: User-curated living documents
-    """
+    """Subtype of mental model - how it was created."""
 
+    STRUCTURAL = "structural"  # Derived from mission, created upfront
+    EMERGENT = "emergent"  # Discovered from data patterns
+    LEARNED = "learned"  # Formed through reflection
+    PINNED = "pinned"  # User-defined topic, observations LLM-generated
     DIRECTIVE = "directive"  # User-defined hard rules, observations user-provided
 
 
@@ -51,3 +49,50 @@ class MentalModel(BaseModel):
     created_at: datetime = Field(
         default_factory=lambda: datetime.now(timezone.utc), description="When this model was created"
     )
+
+
+class StructuralModelTemplate(BaseModel):
+    """
+    A template for a structural mental model.
+
+    Generated by LLM based on the bank's mission. Represents what any agent
+    with this role would need to track.
+    """
+
+    id: str = Field(default="", description="Existing model ID to keep, or empty for new models")
+    name: str = Field(description="Human-readable name")
+    description: str = Field(description="What this model should track")
+    initial_probes: list[str] = Field(default_factory=list, description="Initial search queries to populate this model")
+
+
+class StructuralModelDerivationResponse(BaseModel):
+    """Response from LLM for structural model derivation."""
+
+    templates: list[StructuralModelTemplate] = Field(description="Structural model templates derived from the mission")
+
+
+class EmergentCandidate(BaseModel):
+    """
+    A candidate for promotion to emergent mental model.
+
+    Detected through pattern analysis of facts.
+    """
+
+    name: str = Field(description="Name of the detected pattern/entity")
+    detection_method: str = Field(description="How this candidate was detected")
+    mention_count: int = Field(default=0, description="How many times referenced")
+    entity_id: str | None = Field(default=None, description="Entity ID if detected as entity")
+    relevance_score: float = Field(default=0.0, description="Score from mission filter (0-1)")
+
+
+class ResearchResult(BaseModel):
+    """
+    Result from the research endpoint.
+
+    Contains the answer along with the mental models and facts used.
+    """
+
+    answer: str = Field(description="The synthesized answer")
+    mental_models_used: list[str] = Field(default_factory=list, description="IDs of mental models that contributed")
+    facts_used: list[str] = Field(default_factory=list, description="Fact IDs that contributed")
+    question_type: str | None = Field(default=None, description="Detected question type (WHO, WHAT, HOW, etc.)")

hindsight-api/hindsight_api/engine/mental_models/structural.py

@@ -0,0 +1,228 @@
+"""
+Structural mental model derivation from bank mission.
+
+Structural models are derived from the bank's mission - they represent what
+any agent with this role would need to track. For example:
+
+Mission: "Be a PM for engineering team"
+Structural models:
+  - Team Structure (who's on the team, roles)
+  - Project Overview (current projects, status)
+  - Processes (how releases work, how decisions are made)
+  - Key Systems (what we own, dependencies)
+"""
+
+import logging
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from .models import StructuralModelTemplate
+
+if TYPE_CHECKING:
+    from ..llm_wrapper import LLMConfig
+
+logger = logging.getLogger(__name__)
+
+
+class StructuralDerivationResponse(BaseModel):
+    """Response from LLM for structural model derivation."""
+
+    templates: list[StructuralModelTemplate] = Field(description="Structural model templates derived from the mission")
+
+
+class StructuralRelevanceResult(BaseModel):
+    """Result of evaluating a structural model's relevance to the mission."""
+
+    name: str
+    relevant: bool
+    reason: str
+
+
+class StructuralRelevanceResponse(BaseModel):
+    """Response from LLM for structural model relevance evaluation."""
+
+    models: list[StructuralRelevanceResult] = Field(description="Relevance evaluation for each model")
+
+
+def build_structural_derivation_prompt(mission: str, existing_models: list[dict] | None = None) -> str:
+    """Build the prompt for deriving structural models from a mission."""
+    existing_section = ""
+    if existing_models:
+        model_list = "\n".join([f"- id='{m['id']}' name='{m['name']}': {m['description']}" for m in existing_models])
+        existing_section = f"""
+EXISTING STRUCTURAL MODELS:
+{model_list}
+
+IMPORTANT: If keeping an existing model, you MUST return its EXACT 'id' value.
+Models not included in your output will be REMOVED.
+"""
+
+    return f"""Given this agent mission, identify the KEY THINGS to track to achieve it.
+
+MISSION: {mission}
+{existing_section}
+IMPORTANT CONSTRAINTS:
+- Return 0-3 structural models MAXIMUM (less is better!)
+- Only include models for SPECIFIC, CONCRETE things the agent needs to track
+- Each model must be DIRECTLY tied to achieving the mission
+- If the mission is simple, return 0 models (empty array is fine)
+- If existing models are provided and you want to keep one, use its EXACT id
+- Do NOT create near-duplicates (e.g., don't create "topic-map" if "topic-connections" exists)
+
+GOOD examples (specific, actionable):
+- Mission: "Be a PM for engineering team" → "Team Members" (track who's on the team)
+- Mission: "Track customer feedback" → "Customer Issues" (track specific complaints/requests)
+- Mission: "Manage project X" → "Project X Milestones" (track progress)
+
+BAD examples (too generic, don't create these):
+- "Processes", "Workflows", "Key Systems", "Important Events"
+- "Communication", "Collaboration", "Progress", "Status"
+- Generic role-based models not tied to the specific mission
+
+For each model:
+1. id: Use EXACT existing id if keeping a model, or leave empty for new models
+2. name: Short, specific name (e.g., "Team Members", "Sprint Goals")
+3. description: One line describing what to track
+4. initial_probes: 2-3 search queries to find relevant information
+
+Return ONLY the models that should exist. Existing models not in your output will be deleted."""
+
+
+def get_structural_derivation_system_message() -> str:
+    """System message for structural model derivation."""
+    return """You identify the key things to track for a mission. Be VERY selective.
+
+Rules:
+- Maximum 3 models (prefer fewer)
+- Only SPECIFIC, CONCRETE things - not generic categories
+- Each must DIRECTLY help achieve the mission
+- Empty array is valid if no models are truly needed
+- If existing models are shown and you want to keep one, return its EXACT id
+- Never create duplicates - if a similar model exists, keep the existing one
+
+Output JSON with 'templates' array (can be empty)."""
+
+
+def _normalize_id(text: str) -> str:
+    """Normalize a string to a canonical form for comparison.
+
+    Removes common suffixes, pluralization, and normalizes separators.
+    """
+    # Lowercase and normalize separators
+    normalized = text.lower().replace(" ", "-").replace("_", "-")
+
+    # Remove common suffixes that indicate the same concept
+    suffixes_to_remove = ["-map", "-list", "-overview", "-tracker", "-s"]
+    for suffix in suffixes_to_remove:
+        if normalized.endswith(suffix) and len(normalized) > len(suffix):
+            normalized = normalized[: -len(suffix)]
+
+    return normalized
+
+
+def _find_similar_existing_id(new_id: str, existing_models: list[dict]) -> str | None:
+    """Find an existing model ID that is similar to the new ID.
+
+    Returns the existing ID if a similar one is found, None otherwise.
+    """
+    if not existing_models:
+        return None
+
+    new_normalized = _normalize_id(new_id)
+
+    for model in existing_models:
+        existing_id = model.get("id", "")
+        existing_normalized = _normalize_id(existing_id)
+
+        # Check if one is a prefix of the other (normalized)
+        if new_normalized.startswith(existing_normalized) or existing_normalized.startswith(new_normalized):
+            return existing_id
+
+        # Check if they're the same when normalized
+        if new_normalized == existing_normalized:
+            return existing_id
+
+    return None
+
+
+async def derive_structural_models(
+    llm_config: "LLMConfig",
+    mission: str,
+    existing_models: list[dict] | None = None,
+) -> tuple[list[StructuralModelTemplate], list[str]]:
+    """
+    Derive structural model templates from a bank's mission.
+
+    This combines derivation and evaluation in one call. The LLM sees existing
+    models and decides which to keep. Any existing model not in the output
+    will be marked for removal.
+
+    Args:
+        llm_config: LLM configuration for calling the model
+        mission: The bank's mission (e.g., "Be a PM for engineering team")
+        existing_models: Optional list of existing model dicts with 'name', 'description', 'id'
+
+    Returns:
+        Tuple of (templates to create/keep, IDs of existing models to remove)
+
+    Raises:
+        Exception: If LLM call fails
+    """
+    prompt = build_structural_derivation_prompt(mission, existing_models)
+
+    result = await llm_config.call(
+        messages=[
+            {"role": "system", "content": get_structural_derivation_system_message()},
+            {"role": "user", "content": prompt},
+        ],
+        response_format=StructuralDerivationResponse,
+        scope="mental_model_structural_derivation",
+    )
+
+    templates = result.templates
+    logger.info(f"[STRUCTURAL] LLM returned {len(templates)} structural models")
+
+    # Build set of existing IDs for quick lookup
+    existing_ids = {m["id"] for m in existing_models} if existing_models else set()
+
+    # Process templates: validate IDs, deduplicate, assign stable IDs
+    processed_templates: list[StructuralModelTemplate] = []
+    kept_existing_ids: set[str] = set()
+
+    for template in templates:
+        # If LLM returned an ID, check if it's a valid existing ID
+        if template.id and template.id in existing_ids:
+            # LLM is keeping an existing model
+            kept_existing_ids.add(template.id)
+            processed_templates.append(template)
+            logger.info(f"[STRUCTURAL] Keeping existing model: {template.id}")
+        else:
+            # New model or LLM didn't return a valid ID
+            # Generate ID from name
+            generated_id = template.name.lower().replace(" ", "-").replace("_", "-")
+
+            # Check for similar existing models to prevent near-duplicates
+            similar_id = _find_similar_existing_id(generated_id, existing_models)
+            if similar_id and similar_id not in kept_existing_ids:
+                # Use the existing similar model instead of creating a new one
+                logger.info(f"[STRUCTURAL] Detected near-duplicate: '{generated_id}' matches existing '{similar_id}'")
+                template.id = similar_id
+                kept_existing_ids.add(similar_id)
+            else:
+                template.id = generated_id
+
+            processed_templates.append(template)
+
+    # Find existing models to remove (not kept in LLM output)
+    models_to_remove = []
+    if existing_models:
+        for model in existing_models:
+            if model["id"] not in kept_existing_ids:
+                logger.info(f"[STRUCTURAL] Marking '{model['name']}' (id={model['id']}) for removal")
+                models_to_remove.append(model["id"])
+
+    if models_to_remove:
+        logger.info(f"[STRUCTURAL] {len(models_to_remove)} existing models will be removed")
+
+    return processed_templates, models_to_remove

hindsight-api/hindsight_api/engine/reflect/__init__.py

@@ -4,15 +4,17 @@ Reflect agent module for agentic reflection with tools.
 The reflect agent uses an iterative loop with tools to:
 1. Lookup mental models (existing knowledge)
 2. Recall facts (semantic + temporal search)
-3. Expand memories (get chunk/document context)
+3. Learn new insights (create/update mental models)
+4. Expand memories (get chunk/document context)
 """
 
 from .agent import ReflectAgentResult, run_reflect_agent
-from .models import ReflectAction, ReflectActionBatch
+from .models import MentalModelInput, ReflectAction, ReflectActionBatch
 
 __all__ = [
     "run_reflect_agent",
     "ReflectAgentResult",
     "ReflectAction",
     "ReflectActionBatch",
+    "MentalModelInput",
 ]

hindsight-api/hindsight_api/engine/reflect/agent.py

@@ -1,31 +1,20 @@
 """
 Reflect agent - agentic loop for reflection with native tool calling.
-
-Uses hierarchical retrieval:
-1. search_mental_models - User-curated summaries (highest quality)
-2. search_observations - Consolidated knowledge with freshness
-3. recall - Raw facts as ground truth
 """
 
 import asyncio
 import json
 import logging
-import re
 import time
 from typing import TYPE_CHECKING, Any, Awaitable, Callable
 
-from .models import DirectiveInfo, LLMCall, ReflectAgentResult, TokenUsageSummary, ToolCall
+from .models import DirectiveInfo, LLMCall, MentalModelInput, ReflectAgentResult, ToolCall
 from .prompts import FINAL_SYSTEM_PROMPT, _extract_directive_rules, build_final_prompt, build_system_prompt_for_tools
 from .tools_schema import get_reflect_tools
 
 
 def _build_directives_applied(directives: list[dict[str, Any]] | None) -> list[DirectiveInfo]:
-    """Build list of DirectiveInfo from directive mental models.
-
-    Handles multiple directive formats:
-    1. New format: directives have direct 'content' field
-    2. Fallback: directives have 'description' field
-    """
+    """Build list of DirectiveInfo from directive mental models."""
     if not directives:
         return []
 
@@ -33,11 +22,17 @@ def _build_directives_applied(directives: list[dict[str, Any]] | None) -> list[D
     for directive in directives:
         directive_id = directive.get("id", "")
         directive_name = directive.get("name", "")
+        observations = directive.get("observations", [])
 
-        # Get content from 'content' field or fallback to 'description'
-        content = directive.get("content", "") or directive.get("description", "")
+        rules = []
+        for obs in observations:
+            # Support both Pydantic Observation objects and dicts
+            if hasattr(obs, "content"):
+                rules.append(obs.content)
+            elif isinstance(obs, dict) and obs.get("content"):
+                rules.append(obs["content"])
 
-        result.append(DirectiveInfo(id=directive_id, name=directive_name, content=content))
+        result.append(DirectiveInfo(id=directive_id, name=directive_name, rules=rules))
 
     return result
 
@@ -51,98 +46,12 @@ logger = logging.getLogger(__name__)
 DEFAULT_MAX_ITERATIONS = 10
 
 
-def _normalize_tool_name(name: str) -> str:
-    """Normalize tool name from various LLM output formats.
-
-    Some LLMs output tool names in non-standard formats:
-    - 'functions.done' (OpenAI-style prefix)
-    - 'call=functions.done' (some models)
-    - 'call=done' (some models)
-    - 'done<|channel|>commentary' (malformed special tokens appended)
-
-    Returns the normalized tool name (e.g., 'done', 'recall', etc.)
-    """
-    # Handle 'call=functions.name' or 'call=name' format
-    if name.startswith("call="):
-        name = name[len("call=") :]
-
-    # Handle 'functions.name' format
-    if name.startswith("functions."):
-        name = name[len("functions.") :]
-
-    # Handle malformed special tokens appended to tool name
-    # e.g., 'done<|channel|>commentary' -> 'done'
-    if "<|" in name:
-        name = name.split("<|")[0]
-
-    return name
-
-
-def _is_done_tool(name: str) -> bool:
-    """Check if the tool name represents the 'done' tool."""
-    return _normalize_tool_name(name) == "done"
-
-
-# Pattern to match done() call as text - handles done({...}) with nested JSON
-_DONE_CALL_PATTERN = re.compile(r"done\s*\(\s*\{.*$", re.DOTALL)
-
-# Patterns for leaked structured output in the answer field
-_LEAKED_JSON_SUFFIX = re.compile(
-    r'\s*```(?:json)?\s*\{[^}]*(?:"(?:observation_ids|memory_ids|mental_model_ids)"|\})\s*```\s*$',
-    re.DOTALL | re.IGNORECASE,
-)
-_LEAKED_JSON_OBJECT = re.compile(
-    r'\s*\{[^{]*"(?:observation_ids|memory_ids|mental_model_ids|answer)"[^}]*\}\s*$', re.DOTALL
-)
-_TRAILING_IDS_PATTERN = re.compile(
-    r"\s*(?:observation_ids|memory_ids|mental_model_ids)\s*[=:]\s*\[.*?\]\s*$", re.DOTALL | re.IGNORECASE
-)
-
-
-def _clean_answer_text(text: str) -> str:
-    """Clean up answer text by removing any done() tool call syntax.
-
-    Some LLMs output the done() call as text instead of a proper tool call.
-    This strips out patterns like: done({"answer": "...", ...})
-    """
-    # Remove done() call pattern from the end of the text
-    cleaned = _DONE_CALL_PATTERN.sub("", text).strip()
-    return cleaned if cleaned else text
-
-
-def _clean_done_answer(text: str) -> str:
-    """Clean up the answer field from a done() tool call.
-
-    Some LLMs leak structured output patterns into the answer text, such as:
-    - JSON code blocks with observation_ids/memory_ids at the end
-    - Raw JSON objects with these fields
-    - Plain text like "observation_ids: [...]"
-
-    This cleans those patterns while preserving the actual answer content.
-    """
-    if not text:
-        return text
-
-    cleaned = text
-
-    # Remove leaked JSON in code blocks at the end
-    cleaned = _LEAKED_JSON_SUFFIX.sub("", cleaned).strip()
-
-    # Remove leaked raw JSON objects at the end
-    cleaned = _LEAKED_JSON_OBJECT.sub("", cleaned).strip()
-
-    # Remove trailing ID patterns
-    cleaned = _TRAILING_IDS_PATTERN.sub("", cleaned).strip()
-
-    return cleaned if cleaned else text
-
-
 async def _generate_structured_output(
     answer: str,
     response_schema: dict,
     llm_config: "LLMProvider",
     reflect_id: str,
-) -> tuple[dict[str, Any] | None, int, int]:
+) -> dict[str, Any] | None:
     """Generate structured output from an answer using the provided JSON schema.
 
     Args:
@@ -152,8 +61,7 @@ async def _generate_structured_output(
         reflect_id: Reflect ID for logging
 
     Returns:
-        Tuple of (structured_output, input_tokens, output_tokens).
-        structured_output is None if generation fails.
+        Structured output dict if successful, None otherwise
     """
     try:
         from typing import Any as TypingAny
@@ -186,62 +94,41 @@ async def _generate_structured_output(
             fields[field_name] = (field_type, default)
 
         if not fields:
-            logger.warning(f"[REFLECT {reflect_id}] No fields found in response_schema, skipping structured output")
-            return None, 0, 0
+            return None
 
         DynamicModel = create_model("StructuredResponse", **fields)
 
         # Include the full schema in the prompt for better LLM guidance
         schema_str = json.dumps(response_schema, indent=2)
 
-        # Build field descriptions for the prompt
-        field_descriptions = []
-        for field_name, field_schema in schema_props.items():
-            field_type = field_schema.get("type", "string")
-            field_desc = field_schema.get("description", "")
-            is_required = field_name in required_fields
-            req_marker = " (REQUIRED)" if is_required else " (optional)"
-            field_descriptions.append(f"- {field_name} ({field_type}){req_marker}: {field_desc}")
-        fields_text = "\n".join(field_descriptions)
-
         # Call LLM with the answer to extract structured data
-        structured_prompt = f"""Your task is to extract specific information from the answer below and format it as JSON.
+        structured_prompt = f"""Based on this answer, extract the information into the requested structured format.
 
-ANSWER TO EXTRACT FROM:
-\"\"\"
-{answer}
-\"\"\"
+Answer: {answer}
 
-REQUIRED OUTPUT FORMAT - Extract the following fields from the answer above:
-{fields_text}
-
-JSON Schema:
+JSON Schema to follow:
 ```json
 {schema_str}
 ```
 
-INSTRUCTIONS:
-1. Read the answer carefully and identify the information that matches each field
-2. Extract the ACTUAL content from the answer - do NOT leave fields empty if information is present
-3. For string fields: use the exact text or a clear summary from the answer
-4. For array fields: return a JSON array (e.g., ["item1", "item2"]), NOT a string
-5. For required fields: you MUST provide a value extracted from the answer
-6. Return ONLY the JSON object, no explanation
+Return ONLY a valid JSON object that matches this exact schema. Pay special attention to field types:
+- "type": "array" means the value must be a JSON array/list, NOT a string
+- "type": "string" means the value must be a string
+- "type": "object" means the value must be a JSON object
 
-OUTPUT:"""
+Do not include any explanation, only the JSON object."""
 
-        structured_result, usage = await llm_config.call(
+        structured_result = await llm_config.call(
             messages=[
                 {
                     "role": "system",
-                    "content": "You are a precise data extraction assistant. Extract information from text and return it as valid JSON matching the provided schema. Always extract actual content - never return empty strings for required fields if information is available.",
+                    "content": "Extract structured data from the given answer. Return only valid JSON matching the provided schema exactly.",
                 },
                 {"role": "user", "content": structured_prompt},
             ],
             response_format=DynamicModel,
             scope="reflect_structured",
             skip_validation=True,  # We'll handle the dict ourselves
-            return_usage=True,
         )
 
         # Convert to dict
@@ -253,18 +140,12 @@ OUTPUT:"""
             # Try to parse as JSON
             structured_output = json.loads(str(structured_result))
 
-        # Validate that required fields have non-empty values
-        for field_name in required_fields:
-            value = structured_output.get(field_name)
-            if value is None or value == "" or value == []:
-                logger.warning(f"[REFLECT {reflect_id}] Required field '{field_name}' is empty in structured output")
-
         logger.info(f"[REFLECT {reflect_id}] Generated structured output with {len(structured_output)} fields")
-        return structured_output, usage.input_tokens, usage.output_tokens
+        return structured_output
 
     except Exception as e:
         logger.warning(f"[REFLECT {reflect_id}] Failed to generate structured output: {e}")
-        return None, 0, 0
+        return None
 
 
 async def run_reflect_agent(
@@ -272,35 +153,32 @@ async def run_reflect_agent(
     bank_id: str,
     query: str,
     bank_profile: dict[str, Any],
-    search_mental_models_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
-    search_observations_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
+    lookup_fn: Callable[[str | None], Awaitable[dict[str, Any]]],
     recall_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
     expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
+    learn_fn: Callable[[MentalModelInput], Awaitable[dict[str, Any]]] | None = None,
     context: str | None = None,
     max_iterations: int = DEFAULT_MAX_ITERATIONS,
     max_tokens: int | None = None,
     response_schema: dict | None = None,
     directives: list[dict[str, Any]] | None = None,
-    has_mental_models: bool = False,
-    budget: str | None = None,
 ) -> ReflectAgentResult:
     """
     Execute the reflect agent loop using native tool calling.
 
-    The agent uses hierarchical retrieval:
-    1. search_mental_models - User-curated summaries (try first)
-    2. search_observations - Consolidated knowledge with freshness
-    3. recall - Raw facts as ground truth
+    The agent iteratively calls tools to gather information and learn,
+    then provides a final answer via the done() tool.
 
     Args:
         llm_config: LLM provider for agent calls
         bank_id: Bank identifier
         query: Question to answer
         bank_profile: Bank profile with name and mission
-        search_mental_models_fn: Tool callback for searching mental models (query, max_results) -> result
-        search_observations_fn: Tool callback for searching observations (query, max_results) -> result
+        lookup_fn: Tool callback for lookup (model_id) -> result
         recall_fn: Tool callback for recall (query, max_tokens) -> result
-        expand_fn: Tool callback for expand (memory_ids, depth) -> result
+        expand_fn: Tool callback for expand (memory_id, depth) -> result
+        learn_fn: Optional tool callback for learn (MentalModelInput) -> result.
+                  If None, learn tool is disabled.
         context: Optional additional context
         max_iterations: Maximum number of iterations before forcing response
         max_tokens: Maximum tokens for the final response
@@ -310,6 +188,7 @@ async def run_reflect_agent(
     Returns:
         ReflectAgentResult with final answer and metadata
     """
+    enable_learn = learn_fn is not None
     reflect_id = f"{bank_id[:8]}-{int(time.time() * 1000) % 100000}"
     start_time = time.time()
 
@@ -320,50 +199,67 @@ async def run_reflect_agent(
     directive_rules = _extract_directive_rules(directives) if directives else None
 
     # Get tools for this agent (with directive compliance field if directives exist)
-    tools = get_reflect_tools(directive_rules=directive_rules)
+    tools = get_reflect_tools(enable_learn=enable_learn, directive_rules=directive_rules)
 
     # Build initial messages (directives are injected into system prompt at START and END)
-    system_prompt = build_system_prompt_for_tools(
-        bank_profile, context, directives=directives, has_mental_models=has_mental_models, budget=budget
-    )
+    system_prompt = build_system_prompt_for_tools(bank_profile, context, directives=directives)
     messages: list[dict[str, Any]] = [
         {"role": "system", "content": system_prompt},
         {"role": "user", "content": query},
     ]
 
     # Tracking
+    mental_models_created: list[str] = []
     total_tools_called = 0
     tool_trace: list[ToolCall] = []
     tool_trace_summary: list[dict[str, Any]] = []
     llm_trace: list[dict[str, Any]] = []
     context_history: list[dict[str, Any]] = []  # For final prompt fallback
 
-    # Token usage tracking - accumulate across all LLM calls
-    total_input_tokens = 0
-    total_output_tokens = 0
-
     # Track available IDs for validation (prevents hallucinated citations)
     available_memory_ids: set[str] = set()
-    available_mental_model_ids: set[str] = set()
-    available_observation_ids: set[str] = set()
+    available_model_ids: set[str] = set()
+
+    # Pre-fetch mental models so the agent always starts with this knowledge
+    prefetch_start = time.time()
+    models_result = await lookup_fn(None)  # List all mental models
+    prefetch_duration = int((time.time() - prefetch_start) * 1000)
+
+    # Track available model IDs
+    if isinstance(models_result, dict) and "models" in models_result:
+        for model in models_result["models"]:
+            if "id" in model:
+                available_model_ids.add(model["id"])
+
+    # Add to context history for the agent
+    context_history.append({"tool": "list_mental_models", "output": models_result})
+
+    # Add to tool trace
+    tool_trace.append(
+        ToolCall(
+            tool="list_mental_models",
+            input={"tool": "list_mental_models"},
+            output=models_result,
+            duration_ms=prefetch_duration,
+            iteration=0,
+        )
+    )
+    tool_trace_summary.append(
+        {
+            "tool": "list_mental_models",
+            "input_summary": "(prefetch)",
+            "duration_ms": prefetch_duration,
+            "output_chars": len(json.dumps(models_result, default=str)),
+        }
+    )
+    total_tools_called += 1
+
+    # Include in the user message so the agent sees it
+    models_info = json.dumps(models_result, indent=2, default=str)
+    messages[1]["content"] = f"{query}\n\n## Available Mental Models (pre-fetched)\n```json\n{models_info}\n```"
 
     def _get_llm_trace() -> list[LLMCall]:
-        return [
-            LLMCall(
-                scope=c["scope"],
-                duration_ms=c["duration_ms"],
-                input_tokens=c.get("input_tokens", 0),
-                output_tokens=c.get("output_tokens", 0),
-            )
-            for c in llm_trace
-        ]
-
-    def _get_usage() -> TokenUsageSummary:
-        return TokenUsageSummary(
-            input_tokens=total_input_tokens,
-            output_tokens=total_output_tokens,
-            total_tokens=total_input_tokens + total_output_tokens,
-        )
+        return [LLMCall(scope=c["scope"], duration_ms=c["duration_ms"]) for c in llm_trace]
 
     def _log_completion(answer: str, iterations: int, forced: bool = False):
         elapsed_ms = int((time.time() - start_time) * 1000)
@@ -397,36 +293,21 @@ async def run_reflect_agent(
             # Force text response on last iteration - no tools
             prompt = build_final_prompt(query, context_history, bank_profile, context)
             llm_start = time.time()
-            response, usage = await llm_config.call(
+            response = await llm_config.call(
                 messages=[
                     {"role": "system", "content": FINAL_SYSTEM_PROMPT},
                     {"role": "user", "content": prompt},
                 ],
                 scope="reflect_agent_final",
                 max_completion_tokens=max_tokens,
-                return_usage=True,
             )
-            llm_duration = int((time.time() - llm_start) * 1000)
-            total_input_tokens += usage.input_tokens
-            total_output_tokens += usage.output_tokens
-            llm_trace.append(
-                {
-                    "scope": "final",
-                    "duration_ms": llm_duration,
-                    "input_tokens": usage.input_tokens,
-                    "output_tokens": usage.output_tokens,
-                }
-            )
-            answer = _clean_answer_text(response.strip())
+            llm_trace.append({"scope": "final", "duration_ms": int((time.time() - llm_start) * 1000)})
+            answer = response.strip()
 
             # Generate structured output if schema provided
             structured_output = None
             if response_schema and answer:
-                structured_output, struct_in, struct_out = await _generate_structured_output(
-                    answer, response_schema, llm_config, reflect_id
-                )
-                total_input_tokens += struct_in
-                total_output_tokens += struct_out
+                structured_output = await _generate_structured_output(answer, response_schema, llm_config, reflect_id)
 
             _log_completion(answer, iteration + 1, forced=True)
             return ReflectAgentResult(
@@ -434,9 +315,9 @@ async def run_reflect_agent(
                 structured_output=structured_output,
                 iterations=iteration + 1,
                 tools_called=total_tools_called,
+                mental_models_created=mental_models_created,
                 tool_trace=tool_trace,
                 llm_trace=_get_llm_trace(),
-                usage=_get_usage(),
                 directives_applied=directives_applied,
             )
 
@@ -451,59 +332,33 @@ async def run_reflect_agent(
                 tool_choice="required" if iteration == 0 else "auto",  # Force tool use on first iteration
             )
             llm_duration = int((time.time() - llm_start) * 1000)
-            total_input_tokens += result.input_tokens
-            total_output_tokens += result.output_tokens
-            llm_trace.append(
-                {
-                    "scope": f"agent_{iteration + 1}",
-                    "duration_ms": llm_duration,
-                    "input_tokens": result.input_tokens,
-                    "output_tokens": result.output_tokens,
-                }
-            )
+            llm_trace.append({"scope": f"agent_{iteration + 1}", "duration_ms": llm_duration})
 
-        except Exception as e:
-            err_duration = int((time.time() - llm_start) * 1000)
-            logger.warning(f"[REFLECT {reflect_id}] LLM error on iteration {iteration + 1}: {e} ({err_duration}ms)")
-            llm_trace.append({"scope": f"agent_{iteration + 1}_err", "duration_ms": err_duration})
-            # Guardrail: If no evidence gathered yet, retry
-            has_gathered_evidence = (
-                bool(available_memory_ids) or bool(available_mental_model_ids) or bool(available_observation_ids)
+        except Exception:
+            llm_trace.append(
+                {"scope": f"agent_{iteration + 1}_err", "duration_ms": int((time.time() - llm_start) * 1000)}
             )
+            # Guardrail: If no evidence gathered yet, retry
+            has_gathered_evidence = bool(available_memory_ids) or bool(available_model_ids)
             if not has_gathered_evidence and iteration < max_iterations - 1:
                 continue
             prompt = build_final_prompt(query, context_history, bank_profile, context)
             llm_start = time.time()
-            response, usage = await llm_config.call(
+            response = await llm_config.call(
                 messages=[
                     {"role": "system", "content": FINAL_SYSTEM_PROMPT},
                     {"role": "user", "content": prompt},
                 ],
                 scope="reflect_agent_final",
                 max_completion_tokens=max_tokens,
-                return_usage=True,
             )
-            llm_duration = int((time.time() - llm_start) * 1000)
-            total_input_tokens += usage.input_tokens
-            total_output_tokens += usage.output_tokens
-            llm_trace.append(
-                {
-                    "scope": "final",
-                    "duration_ms": llm_duration,
-                    "input_tokens": usage.input_tokens,
-                    "output_tokens": usage.output_tokens,
-                }
-            )
-            answer = _clean_answer_text(response.strip())
+            llm_trace.append({"scope": "final", "duration_ms": int((time.time() - llm_start) * 1000)})
+            answer = response.strip()
 
             # Generate structured output if schema provided
             structured_output = None
             if response_schema and answer:
-                structured_output, struct_in, struct_out = await _generate_structured_output(
-                    answer, response_schema, llm_config, reflect_id
-                )
-                total_input_tokens += struct_in
-                total_output_tokens += struct_out
+                structured_output = await _generate_structured_output(answer, response_schema, llm_config, reflect_id)
 
             _log_completion(answer, iteration + 1, forced=True)
             return ReflectAgentResult(
@@ -511,25 +366,23 @@ async def run_reflect_agent(
                 structured_output=structured_output,
                 iterations=iteration + 1,
                 tools_called=total_tools_called,
+                mental_models_created=mental_models_created,
                 tool_trace=tool_trace,
                 llm_trace=_get_llm_trace(),
-                usage=_get_usage(),
                 directives_applied=directives_applied,
             )
 
         # No tool calls - LLM wants to respond with text
         if not result.tool_calls:
             if result.content:
-                answer = _clean_answer_text(result.content.strip())
+                answer = result.content.strip()
 
                 # Generate structured output if schema provided
                 structured_output = None
                 if response_schema and answer:
-                    structured_output, struct_in, struct_out = await _generate_structured_output(
+                    structured_output = await _generate_structured_output(
                         answer, response_schema, llm_config, reflect_id
                     )
-                    total_input_tokens += struct_in
-                    total_output_tokens += struct_out
 
                 _log_completion(answer, iteration + 1)
                 return ReflectAgentResult(
@@ -537,44 +390,29 @@ async def run_reflect_agent(
                     structured_output=structured_output,
                     iterations=iteration + 1,
                     tools_called=total_tools_called,
+                    mental_models_created=mental_models_created,
                     tool_trace=tool_trace,
                     llm_trace=_get_llm_trace(),
-                    usage=_get_usage(),
                     directives_applied=directives_applied,
                 )
             # Empty response, force final
             prompt = build_final_prompt(query, context_history, bank_profile, context)
             llm_start = time.time()
-            response, usage = await llm_config.call(
+            response = await llm_config.call(
                 messages=[
                     {"role": "system", "content": FINAL_SYSTEM_PROMPT},
                     {"role": "user", "content": prompt},
                 ],
                 scope="reflect_agent_final",
                 max_completion_tokens=max_tokens,
-                return_usage=True,
             )
-            llm_duration = int((time.time() - llm_start) * 1000)
-            total_input_tokens += usage.input_tokens
-            total_output_tokens += usage.output_tokens
-            llm_trace.append(
-                {
-                    "scope": "final",
-                    "duration_ms": llm_duration,
-                    "input_tokens": usage.input_tokens,
-                    "output_tokens": usage.output_tokens,
-                }
-            )
-            answer = _clean_answer_text(response.strip())
+            llm_trace.append({"scope": "final", "duration_ms": int((time.time() - llm_start) * 1000)})
+            answer = response.strip()
 
             # Generate structured output if schema provided
             structured_output = None
             if response_schema and answer:
-                structured_output, struct_in, struct_out = await _generate_structured_output(
-                    answer, response_schema, llm_config, reflect_id
-                )
-                total_input_tokens += struct_in
-                total_output_tokens += struct_out
+                structured_output = await _generate_structured_output(answer, response_schema, llm_config, reflect_id)
 
             _log_completion(answer, iteration + 1, forced=True)
             return ReflectAgentResult(
@@ -582,19 +420,17 @@ async def run_reflect_agent(
                 structured_output=structured_output,
                 iterations=iteration + 1,
                 tools_called=total_tools_called,
+                mental_models_created=mental_models_created,
                 tool_trace=tool_trace,
                 llm_trace=_get_llm_trace(),
-                usage=_get_usage(),
                 directives_applied=directives_applied,
             )
 
-        # Check for done tool call (handle various LLM output formats)
-        done_call = next((tc for tc in result.tool_calls if _is_done_tool(tc.name)), None)
+        # Check for done tool call (handle both 'done' and 'functions.done')
+        done_call = next((tc for tc in result.tool_calls if tc.name == "done" or tc.name == "functions.done"), None)
         if done_call:
             # Guardrail: Require evidence before done
-            has_gathered_evidence = (
-                bool(available_memory_ids) or bool(available_mental_model_ids) or bool(available_observation_ids)
-            )
+            has_gathered_evidence = bool(available_memory_ids) or bool(available_model_ids)
             if not has_gathered_evidence and iteration < max_iterations - 1:
                 # Add assistant message and fake tool result asking for evidence
                 messages.append(
@@ -607,10 +443,9 @@ async def run_reflect_agent(
                     {
                         "role": "tool",
                         "tool_call_id": done_call.id,
-                        "name": done_call.name,  # Required by Gemini
                         "content": json.dumps(
                             {
-                                "error": "You must search for information first. Use search_mental_models(), search_observations(), or recall() before providing your final answer."
+                                "error": "You must call recall() or list_mental_models() to gather evidence before providing your final answer."
                             }
                         ),
                     }
@@ -621,13 +456,12 @@ async def run_reflect_agent(
             return await _process_done_tool(
                 done_call,
                 available_memory_ids,
-                available_mental_model_ids,
-                available_observation_ids,
+                available_model_ids,
                 iteration + 1,
                 total_tools_called,
+                mental_models_created,
                 tool_trace,
                 _get_llm_trace(),
-                _get_usage(),
                 _log_completion,
                 reflect_id,
                 directives_applied=directives_applied,
@@ -635,8 +469,8 @@ async def run_reflect_agent(
                 response_schema=response_schema,
             )
 
-        # Execute other tools in parallel (exclude done tool in all its format variants)
-        other_tools = [tc for tc in result.tool_calls if not _is_done_tool(tc.name)]
+        # Execute other tools in parallel (exclude done and functions.done)
+        other_tools = [tc for tc in result.tool_calls if tc.name not in ("done", "functions.done")]
         if other_tools:
             # Add assistant message with tool calls
             messages.append(
@@ -648,14 +482,7 @@ async def run_reflect_agent(
 
             # Execute tools in parallel
             tool_tasks = [
-                _execute_tool_with_timing(
-                    tc,
-                    search_mental_models_fn,
-                    search_observations_fn,
-                    recall_fn,
-                    expand_fn,
-                )
-                for tc in other_tools
+                _execute_tool_with_timing(tc, lookup_fn, recall_fn, expand_fn, learn_fn) for tc in other_tools
             ]
             tool_results = await asyncio.gather(*tool_tasks, return_exceptions=True)
             total_tools_called += len(other_tools)
@@ -663,52 +490,43 @@ async def run_reflect_agent(
             # Process results and add to messages
             for tc, result_data in zip(other_tools, tool_results):
                 if isinstance(result_data, Exception):
-                    # Tool execution failed - send error back to LLM so it can try again
-                    logger.warning(f"[REFLECT {reflect_id}] Tool {tc.name} failed with exception: {result_data}")
-                    output = {"error": f"Tool execution failed: {result_data}"}
-                    duration_ms = 0
-                else:
-                    output, duration_ms = result_data
+                    # Tool execution failed - log and raise to fail the request
+                    logger.error(f"[REFLECT {reflect_id}] Tool {tc.name} failed with exception: {result_data}")
+                    raise RuntimeError(f"Reflect tool '{tc.name}' failed: {result_data}")
 
-                # Normalize tool name for consistent tracking
-                normalized_tool_name = _normalize_tool_name(tc.name)
+                output, duration_ms = result_data
 
-                # Check if tool returned an error response - log but continue (LLM will see the error)
+                # Check if tool returned an error response
                 if isinstance(output, dict) and "error" in output:
-                    logger.warning(
-                        f"[REFLECT {reflect_id}] Tool {normalized_tool_name} returned error: {output['error']}"
-                    )
+                    logger.error(f"[REFLECT {reflect_id}] Tool {tc.name} returned error: {output['error']}")
+                    raise RuntimeError(f"Reflect tool '{tc.name}' error: {output['error']}")
 
-                # Track available IDs from tool results (only for successful responses)
-                if (
-                    normalized_tool_name == "search_mental_models"
-                    and isinstance(output, dict)
-                    and "mental_models" in output
-                ):
-                    for mm in output["mental_models"]:
-                        if "id" in mm:
-                            available_mental_model_ids.add(mm["id"])
+                # Track created mental models
+                if tc.name == "learn" and isinstance(output, dict) and "model_id" in output:
+                    mental_models_created.append(output["model_id"])
 
-                if (
-                    normalized_tool_name == "search_observations"
-                    and isinstance(output, dict)
-                    and "observations" in output
-                ):
-                    for obs in output["observations"]:
-                        if "id" in obs:
-                            available_observation_ids.add(obs["id"])
-
-                if normalized_tool_name == "recall" and isinstance(output, dict) and "memories" in output:
+                # Track available memory IDs from recall
+                if tc.name == "recall" and isinstance(output, dict) and "memories" in output:
                     for memory in output["memories"]:
                         if "id" in memory:
                             available_memory_ids.add(memory["id"])
 
+                # Track available model IDs
+                if tc.name in ("list_mental_models", "get_mental_model") and isinstance(output, dict):
+                    if output.get("found") and "model" in output:
+                        model_id = output["model"].get("id")
+                        if model_id:
+                            available_model_ids.add(model_id)
+                    elif "models" in output:
+                        for model in output["models"]:
+                            if "id" in model:
+                                available_model_ids.add(model["id"])
+
                 # Add tool result message
                 messages.append(
                     {
                         "role": "tool",
                         "tool_call_id": tc.id,
-                        "name": tc.name,  # Required by Gemini
                         "content": json.dumps(output, default=str),
                     }
                 )
@@ -717,17 +535,9 @@ async def run_reflect_agent(
                 input_dict = {"tool": tc.name, **tc.arguments}
                 input_summary = _summarize_input(tc.name, tc.arguments)
 
-                # Extract reason from tool arguments (if provided)
-                tool_reason = tc.arguments.get("reason")
-
                 tool_trace.append(
                     ToolCall(
-                        tool=tc.name,
-                        reason=tool_reason,
-                        input=input_dict,
-                        output=output,
-                        duration_ms=duration_ms,
-                        iteration=iteration + 1,
+                        tool=tc.name, input=input_dict, output=output, duration_ms=duration_ms, iteration=iteration + 1
                     )
                 )
 
@@ -755,9 +565,9 @@ async def run_reflect_agent(
         text=answer,
         iterations=max_iterations,
         tools_called=total_tools_called,
+        mental_models_created=mental_models_created,
         tool_trace=tool_trace,
         llm_trace=_get_llm_trace(),
-        usage=_get_usage(),
         directives_applied=directives_applied,
     )
 
@@ -777,13 +587,12 @@ def _tool_call_to_dict(tc: "LLMToolCall") -> dict[str, Any]:
 async def _process_done_tool(
     done_call: "LLMToolCall",
     available_memory_ids: set[str],
-    available_mental_model_ids: set[str],
-    available_observation_ids: set[str],
+    available_model_ids: set[str],
     iterations: int,
     total_tools_called: int,
+    mental_models_created: list[str],
     tool_trace: list[ToolCall],
     llm_trace: list[LLMCall],
-    usage: TokenUsageSummary,
     log_completion: Callable,
     reflect_id: str,
     directives_applied: list[DirectiveInfo],
@@ -793,30 +602,18 @@ async def _process_done_tool(
     """Process the done tool call and return the result."""
     args = done_call.arguments
 
-    # Extract and clean the answer - some LLMs leak structured output into the answer text
-    raw_answer = args.get("answer", "").strip()
-    answer = _clean_done_answer(raw_answer) if raw_answer else ""
+    answer = args.get("answer", "").strip()
     if not answer:
         answer = "No answer provided."
 
-    # Validate IDs (only include IDs that were actually retrieved)
+    # Validate IDs
     used_memory_ids = [mid for mid in args.get("memory_ids", []) if mid in available_memory_ids]
-    used_mental_model_ids = [mid for mid in args.get("mental_model_ids", []) if mid in available_mental_model_ids]
-    used_observation_ids = [oid for oid in args.get("observation_ids", []) if oid in available_observation_ids]
+    used_model_ids = [mid for mid in args.get("model_ids", []) if mid in available_model_ids]
 
     # Generate structured output if schema provided
     structured_output = None
-    final_usage = usage
     if response_schema and llm_config and answer:
-        structured_output, struct_in, struct_out = await _generate_structured_output(
-            answer, response_schema, llm_config, reflect_id
-        )
-        # Add structured output tokens to usage
-        final_usage = TokenUsageSummary(
-            input_tokens=usage.input_tokens + struct_in,
-            output_tokens=usage.output_tokens + struct_out,
-            total_tokens=usage.total_tokens + struct_in + struct_out,
-        )
+        structured_output = await _generate_structured_output(answer, response_schema, llm_config, reflect_id)
 
     log_completion(answer, iterations)
     return ReflectAgentResult(
@@ -824,33 +621,25 @@ async def _process_done_tool(
         structured_output=structured_output,
         iterations=iterations,
         tools_called=total_tools_called,
+        mental_models_created=mental_models_created,
         tool_trace=tool_trace,
         llm_trace=llm_trace,
-        usage=final_usage,
         used_memory_ids=used_memory_ids,
-        used_mental_model_ids=used_mental_model_ids,
-        used_observation_ids=used_observation_ids,
+        used_model_ids=used_model_ids,
         directives_applied=directives_applied,
     )
 
 
 async def _execute_tool_with_timing(
     tc: "LLMToolCall",
-    search_mental_models_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
-    search_observations_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
+    lookup_fn: Callable[[str | None], Awaitable[dict[str, Any]]],
     recall_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
     expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
+    learn_fn: Callable[[MentalModelInput], Awaitable[dict[str, Any]]] | None = None,
 ) -> tuple[dict[str, Any], int]:
     """Execute a tool call and return result with timing."""
     start = time.time()
-    result = await _execute_tool(
-        tc.name,
-        tc.arguments,
-        search_mental_models_fn,
-        search_observations_fn,
-        recall_fn,
-        expand_fn,
-    )
+    result = await _execute_tool(tc.name, tc.arguments, lookup_fn, recall_fn, expand_fn, learn_fn)
     duration_ms = int((time.time() - start) * 1000)
     return result, duration_ms
 
@@ -858,28 +647,24 @@ async def _execute_tool_with_timing(
 async def _execute_tool(
     tool_name: str,
     args: dict[str, Any],
-    search_mental_models_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
-    search_observations_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
+    lookup_fn: Callable[[str | None], Awaitable[dict[str, Any]]],
     recall_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
     expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
+    learn_fn: Callable[[MentalModelInput], Awaitable[dict[str, Any]]] | None = None,
 ) -> dict[str, Any]:
     """Execute a single tool by name."""
-    # Normalize tool name for various LLM output formats
-    tool_name = _normalize_tool_name(tool_name)
+    # Normalize tool name - some LLMs return 'functions.done' instead of 'done'
+    if tool_name.startswith("functions."):
+        tool_name = tool_name[len("functions.") :]
 
-    if tool_name == "search_mental_models":
-        query = args.get("query")
-        if not query:
-            return {"error": "search_mental_models requires a query parameter"}
-        max_results = args.get("max_results") or 5
-        return await search_mental_models_fn(query, max_results)
+    if tool_name == "list_mental_models":
+        return await lookup_fn(None)
 
-    elif tool_name == "search_observations":
-        query = args.get("query")
-        if not query:
-            return {"error": "search_observations requires a query parameter"}
-        max_tokens = max(args.get("max_tokens") or 5000, 1000)  # Default 5000, min 1000
-        return await search_observations_fn(query, max_tokens)
+    elif tool_name == "get_mental_model":
+        model_id = args.get("model_id")
+        if not model_id:
+            return {"error": "get_mental_model requires model_id"}
+        return await lookup_fn(model_id)
 
     elif tool_name == "recall":
         query = args.get("query")
@@ -888,6 +673,15 @@ async def _execute_tool(
         max_tokens = max(args.get("max_tokens") or 2048, 1000)  # Default 2048, min 1000
         return await recall_fn(query, max_tokens)
 
+    elif tool_name == "learn":
+        if learn_fn is None:
+            return {"error": "learn tool is not available"}
+        name = args.get("name")
+        description = args.get("description")
+        if not name or not description:
+            return {"error": "learn requires name and description"}
+        return await learn_fn(MentalModelInput(name=name, description=description))
+
     elif tool_name == "expand":
         memory_ids = args.get("memory_ids", [])
         if not memory_ids:
@@ -901,22 +695,21 @@ async def _execute_tool(
 
 def _summarize_input(tool_name: str, args: dict[str, Any]) -> str:
     """Create a summary of tool input for logging, showing all params."""
-    if tool_name == "search_mental_models":
-        query = args.get("query", "")
-        query_preview = f"'{query[:30]}...'" if len(query) > 30 else f"'{query}'"
-        max_results = args.get("max_results") or 5
-        return f"(query={query_preview}, max_results={max_results})"
-    elif tool_name == "search_observations":
-        query = args.get("query", "")
-        query_preview = f"'{query[:30]}...'" if len(query) > 30 else f"'{query}'"
-        max_tokens = max(args.get("max_tokens") or 5000, 1000)
-        return f"(query={query_preview}, max_tokens={max_tokens})"
+    if tool_name == "list_mental_models":
+        return "()"
+    elif tool_name == "get_mental_model":
+        return f"(model_id={args.get('model_id', '?')})"
     elif tool_name == "recall":
         query = args.get("query", "")
         query_preview = f"'{query[:30]}...'" if len(query) > 30 else f"'{query}'"
         # Show actual value used (default 2048, min 1000)
         max_tokens = max(args.get("max_tokens") or 2048, 1000)
         return f"(query={query_preview}, max_tokens={max_tokens})"
+    elif tool_name == "learn":
+        name = args.get("name", "?")
+        desc = args.get("description", "")
+        desc_preview = f"'{desc[:20]}...'" if len(desc) > 20 else f"'{desc}'"
+        return f"(name='{name}', description={desc_preview})"
     elif tool_name == "expand":
         memory_ids = args.get("memory_ids", [])
         depth = args.get("depth", "chunk")
@@ -925,9 +718,6 @@ def _summarize_input(tool_name: str, args: dict[str, Any]) -> str:
         answer = args.get("answer", "")
         answer_preview = f"'{answer[:30]}...'" if len(answer) > 30 else f"'{answer}'"
         memory_ids = args.get("memory_ids", [])
-        mental_model_ids = args.get("mental_model_ids", [])
-        observation_ids = args.get("observation_ids", [])
-        return (
-            f"(answer={answer_preview}, mem={len(memory_ids)}, mm={len(mental_model_ids)}, obs={len(observation_ids)})"
-        )
+        model_ids = args.get("model_ids", [])
+        return f"(answer={answer_preview}, memory_ids={len(memory_ids)}, model_ids={len(model_ids)})"
     return str(args)

hindsight-api/hindsight_api/engine/reflect/models.py

@@ -7,28 +7,51 @@ from typing import Any, Literal
 from pydantic import BaseModel, Field
 
 
-class ObservationSection(BaseModel):
-    """A section within an observation with its supporting memories."""
+class MentalModelObservation(BaseModel):
+    """An observation within a mental model with its supporting memories."""
 
-    title: str = Field(description="Section header (can be empty for intro)")
-    text: str = Field(description="Section content - no headers, use lists/tables/bold")
+    title: str = Field(description="Observation header (can be empty for intro)")
+    text: str = Field(description="Observation content - no headers, use lists/tables/bold")
+    memory_ids: list[str] = Field(default_factory=list, description="Memory IDs supporting this observation")
+
+
+class MentalModelInput(BaseModel):
+    """Input for the learn tool to create a mental model placeholder.
+
+    The agent only specifies name and description - the actual content/observations
+    are generated during refresh, similar to pinned models.
+    """
+
+    name: str = Field(description="Human-readable name for the mental model")
+    description: str = Field(description="What to track - used as prompt for content generation during refresh")
+    entity_id: str | None = Field(default=None, description="Optional link to existing entity ID")
+
+
+class AnswerSection(BaseModel):
+    """A section of the answer with its supporting evidence (DEPRECATED)."""
+
+    title: str = Field(description="Section header/title")
+    text: str = Field(description="Section content")
     memory_ids: list[str] = Field(default_factory=list, description="Memory IDs supporting this section")
+    model_ids: list[str] = Field(default_factory=list, description="Mental model IDs supporting this section")
 
 
 class ReflectAction(BaseModel):
     """Single action the reflect agent can take."""
 
-    tool: Literal["list_observations", "get_observation", "recall", "expand", "done"] = Field(
-        description="Tool to invoke: list_observations, get_observation, recall, expand, or done"
+    tool: Literal["list_mental_models", "get_mental_model", "recall", "learn", "expand", "done"] = Field(
+        description="Tool to invoke: list_mental_models, get_mental_model, recall, learn, expand, or done"
     )
     # Tool-specific parameters
-    observation_id: str | None = Field(default=None, description="Observation ID for get_observation")
+    model_id: str | None = Field(default=None, description="Mental model ID for get_mental_model")
     query: str | None = Field(default=None, description="Search query for recall")
     max_tokens: int | None = Field(default=None, description="Max tokens for recall results (default 2048)")
+    mental_model: MentalModelInput | None = Field(default=None, description="Mental model to create/update for learn")
     memory_ids: list[str] | None = Field(default=None, description="Memory unit IDs for expand (batched)")
     depth: Literal["chunk", "document"] | None = Field(default=None, description="Expansion depth for expand")
-    observation_sections: list[ObservationSection] | None = Field(
-        default=None, description="Observation sections for done action (when output_mode=observations)"
+    sections: list[AnswerSection] | None = Field(default=None, description="DEPRECATED: Use answer field instead")
+    observations: list[MentalModelObservation] | None = Field(
+        default=None, description="Observations for done action (when output_mode=observations)"
     )
     # Plain text answer fields (for output_mode=answer)
     answer: str | None = Field(default=None, description="Plain text answer for done action (no markdown)")
@@ -50,8 +73,7 @@ class ReflectActionBatch(BaseModel):
 class ToolCall(BaseModel):
     """A single tool call made during reflect."""
 
-    tool: str = Field(description="Tool name: lookup, recall, expand")
-    reason: str | None = Field(default=None, description="Agent's reasoning for making this tool call")
+    tool: str = Field(description="Tool name: lookup, recall, learn, expand")
     input: dict = Field(description="Tool input parameters")
     output: dict = Field(description="Tool output/result")
     duration_ms: int = Field(description="Execution time in milliseconds")
@@ -63,8 +85,6 @@ class LLMCall(BaseModel):
 
     scope: str = Field(description="Call scope: agent_1, agent_2, final, etc.")
     duration_ms: int = Field(description="Execution time in milliseconds")
-    input_tokens: int = Field(default=0, description="Input tokens used")
-    output_tokens: int = Field(default=0, description="Output tokens used")
 
 
 class DirectiveInfo(BaseModel):
@@ -72,15 +92,7 @@ class DirectiveInfo(BaseModel):
 
     id: str = Field(description="Directive mental model ID")
     name: str = Field(description="Directive name")
-    content: str = Field(description="Directive content")
-
-
-class TokenUsageSummary(BaseModel):
-    """Total token usage across all LLM calls."""
-
-    input_tokens: int = Field(default=0, description="Total input tokens used")
-    output_tokens: int = Field(default=0, description="Total output tokens used")
-    total_tokens: int = Field(default=0, description="Total tokens (input + output)")
+    rules: list[str] = Field(default_factory=list, description="Directive rules/observations that were applied")
 
 
 class ReflectAgentResult(BaseModel):
@@ -92,18 +104,11 @@ class ReflectAgentResult(BaseModel):
     )
     iterations: int = Field(default=0, description="Number of iterations taken")
     tools_called: int = Field(default=0, description="Total number of tool calls made")
+    mental_models_created: list[str] = Field(default_factory=list, description="IDs of mental models created/updated")
     tool_trace: list[ToolCall] = Field(default_factory=list, description="Trace of all tool calls made")
     llm_trace: list[LLMCall] = Field(default_factory=list, description="Trace of all LLM calls made")
-    usage: TokenUsageSummary = Field(
-        default_factory=TokenUsageSummary, description="Total token usage across all LLM calls"
-    )
     used_memory_ids: list[str] = Field(default_factory=list, description="Validated memory IDs actually used in answer")
-    used_mental_model_ids: list[str] = Field(
-        default_factory=list, description="Validated mental model IDs actually used in answer"
-    )
-    used_observation_ids: list[str] = Field(
-        default_factory=list, description="Validated observation IDs actually used in answer"
-    )
+    used_model_ids: list[str] = Field(default_factory=list, description="Validated model IDs actually used in answer")
     directives_applied: list[DirectiveInfo] = Field(
         default_factory=list, description="Directive mental models that affected this reflection"
     )

hindsight-api/hindsight_api/engine/reflect/observations.py

@@ -184,3 +184,65 @@ def compute_trend(
         return Trend.WEAKENING
     else:
         return Trend.STABLE
+
+
+class CandidateObservation(BaseModel):
+    """A candidate observation generated during the seed phase.
+
+    Candidates are preliminary observations that need evidence validation
+    before becoming full observations.
+    """
+
+    content: str = Field(description="The proposed observation content")
+    seed_memory_ids: list[str] = Field(default_factory=list, description="Memory IDs that inspired this candidate")
+
+
+class CandidateWithEvidence(BaseModel):
+    """A candidate observation with gathered supporting and contradicting evidence."""
+
+    candidate: CandidateObservation
+    supporting_memories: list[dict] = Field(default_factory=list, description="Memories that support this observation")
+    contradicting_memories: list[dict] = Field(
+        default_factory=list, description="Memories that contradict this observation"
+    )
+
+
+class MentalModelSnapshot(BaseModel):
+    """A versioned snapshot of a mental model's observations.
+
+    Used for tracking changes over time and enabling diff views.
+    """
+
+    version: int = Field(description="Version number (1-indexed)")
+    observations: list[Observation] = Field(default_factory=list, description="Observations at this version")
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc), description="When this version was created"
+    )
+    reflect_summary: str | None = Field(default=None, description="Summary of changes in this version")
+
+
+def verify_evidence_quotes(
+    observation: Observation,
+    memories: dict[str, str],
+) -> tuple[bool, list[str]]:
+    """Verify that all evidence quotes exist in the referenced memories.
+
+    Args:
+        observation: The observation to verify
+        memories: Dict mapping memory_id to memory content
+
+    Returns:
+        Tuple of (is_valid, list of error messages)
+    """
+    errors = []
+
+    for evidence in observation.evidence:
+        memory_content = memories.get(evidence.memory_id)
+        if memory_content is None:
+            errors.append(f"Memory {evidence.memory_id} not found")
+            continue
+
+        if evidence.quote not in memory_content:
+            errors.append(f"Quote not found in memory {evidence.memory_id}: '{evidence.quote[:50]}...'")
+
+    return len(errors) == 0, errors

hindsight-api/hindsight_api/engine/reflect/prompts.py

@@ -1,10 +1,5 @@
 """
 System prompts for the reflect agent.
-
-The reflect agent uses hierarchical retrieval:
-1. search_mental_models - User-curated summaries (highest quality)
-2. search_observations - Consolidated knowledge with freshness awareness
-3. recall - Raw facts as ground truth fallback
 """
 
 import json
@@ -16,7 +11,7 @@ def _extract_directive_rules(directives: list[dict[str, Any]]) -> list[str]:
     Extract directive rules as a list of strings.
 
     Args:
-        directives: List of directives with name and content
+        directives: List of directive mental models with observations
 
     Returns:
         List of directive rule strings
@@ -24,34 +19,25 @@ def _extract_directive_rules(directives: list[dict[str, Any]]) -> list[str]:
     rules = []
     for directive in directives:
         directive_name = directive.get("name", "")
-        # New format: directives have direct content field
-        content = directive.get("content", "")
-        if content:
-            if directive_name:
-                rules.append(f"**{directive_name}**: {content}")
-            else:
-                rules.append(content)
-        else:
-            # Legacy format: check for observations
-            observations = directive.get("observations", [])
-            if observations:
-                for obs in observations:
-                    # Support both Pydantic Observation objects and dicts
-                    if hasattr(obs, "title"):
-                        title = obs.title
-                        obs_content = obs.content
-                    else:
-                        title = obs.get("title", "")
-                        obs_content = obs.get("content", "")
-                    if title and obs_content:
-                        rules.append(f"**{title}**: {obs_content}")
-                    elif obs_content:
-                        rules.append(obs_content)
-            elif directive_name:
-                # Fallback to description
-                desc = directive.get("description", "")
-                if desc:
-                    rules.append(f"**{directive_name}**: {desc}")
+        observations = directive.get("observations", [])
+        if observations:
+            for obs in observations:
+                # Support both Pydantic Observation objects and dicts
+                if hasattr(obs, "title"):
+                    title = obs.title
+                    content = obs.content
+                else:
+                    title = obs.get("title", "")
+                    content = obs.get("content", "")
+                if title and content:
+                    rules.append(f"**{title}**: {content}")
+                elif content:
+                    rules.append(content)
+        elif directive_name:
+            # Fallback to description if no observations
+            desc = directive.get("description", "")
+            if desc:
+                rules.append(f"**{directive_name}**: {desc}")
     return rules
 
 
@@ -125,27 +111,24 @@ def build_system_prompt_for_tools(
     bank_profile: dict[str, Any],
     context: str | None = None,
     directives: list[dict[str, Any]] | None = None,
-    has_mental_models: bool = False,
-    budget: str | None = None,
 ) -> str:
     """
     Build the system prompt for tool-calling reflect agent.
 
-    The agent uses hierarchical retrieval:
-    1. search_mental_models - User-curated summaries (try first, if available)
-    2. search_observations - Consolidated knowledge with freshness
-    3. recall - Raw facts as ground truth
+    This is a simplified prompt since tools are defined separately via the tools parameter.
 
     Args:
         bank_profile: Bank profile with name and mission
         context: Optional additional context
         directives: Optional list of directive mental models to inject as hard rules
-        has_mental_models: Whether the bank has any mental models (skip if not)
-        budget: Search depth budget - "low", "mid", or "high". Controls exploration thoroughness.
     """
     name = bank_profile.get("name", "Assistant")
     mission = bank_profile.get("mission", "")
 
+    no_info_rule = (
+        "- Only say 'I don't have information' AFTER trying list_mental_models AND recall with no relevant results"
+    )
+
     parts = []
 
     # Inject directives at the VERY START for maximum prominence
@@ -164,7 +147,8 @@ def build_system_prompt_for_tools(
             "## CRITICAL RULES",
             "- You must NEVER fabricate information that has no basis in retrieved data",
             "- You SHOULD synthesize, infer, and reason from the retrieved memories",
-            "- You MUST search before saying you don't have information",
+            "- You MUST call recall() before saying you don't have information",
+            no_info_rule,
             "",
             "## How to Reason",
             "- If memories mention someone did an activity, you can infer they likely enjoyed it",
@@ -172,56 +156,7 @@ def build_system_prompt_for_tools(
             "- Be a thoughtful interpreter, not just a literal repeater",
             "- When the exact answer isn't stated, use what IS stated to give the best answer",
             "",
-            "## HIERARCHICAL RETRIEVAL STRATEGY",
-            "",
-        ]
-    )
-
-    # Build retrieval levels based on what's available
-    if has_mental_models:
-        parts.extend(
-            [
-                "You have access to THREE levels of knowledge. Use them in this order:",
-                "",
-                "### 1. MENTAL MODELS (search_mental_models) - Try First",
-                "- User-curated summaries about specific topics",
-                "- HIGHEST quality - manually created and maintained",
-                "- If a relevant mental model exists and is FRESH, it may fully answer the question",
-                "- Check `is_stale` field - if stale, also verify with lower levels",
-                "",
-                "### 2. OBSERVATIONS (search_observations) - Second Priority",
-                "- Auto-consolidated knowledge from memories",
-                "- Check `is_stale` field - if stale, ALSO use recall() to verify",
-                "- Good for understanding patterns and summaries",
-                "",
-                "### 3. RAW FACTS (recall) - Ground Truth",
-                "- Individual memories (world facts and experiences)",
-                "- Use when: no mental models/observations exist, they're stale, or you need specific details",
-                "- This is the source of truth that other levels are built from",
-                "",
-            ]
-        )
-    else:
-        parts.extend(
-            [
-                "You have access to TWO levels of knowledge. Use them in this order:",
-                "",
-                "### 1. OBSERVATIONS (search_observations) - Try First",
-                "- Auto-consolidated knowledge from memories",
-                "- Check `is_stale` field - if stale, ALSO use recall() to verify",
-                "- Good for understanding patterns and summaries",
-                "",
-                "### 2. RAW FACTS (recall) - Ground Truth",
-                "- Individual memories (world facts and experiences)",
-                "- Use when: no observations exist, they're stale, or you need specific details",
-                "- This is the source of truth that observations are built from",
-                "",
-            ]
-        )
-
-    parts.extend(
-        [
-            "## Query Strategy",
+            "## Query Strategy (IMPORTANT)",
             "recall() uses semantic search. NEVER just echo the user's question - decompose it into targeted searches:",
             "",
             "BAD: User asks 'recurring lesson themes between students' → recall('recurring lesson themes between students')",
@@ -229,82 +164,44 @@ def build_system_prompt_for_tools(
             "  1. recall('lessons') - find all lesson-related memories",
             "  2. recall('teaching sessions') - alternative phrasing",
             "  3. recall('student progress') - find student-related memories",
+            "  4. recall('topics taught') - find subject matter",
             "",
             "Think: What ENTITIES and CONCEPTS does this question involve? Search for each separately.",
+            "- Questions about patterns → search for the individual instances first",
+            "- Questions comparing things → search for each thing separately",
+            "- Questions about relationships → search for each party involved",
             "",
+            "## Workflow",
         ]
     )
 
-    # Add budget guidance
-    if budget:
-        budget_lower = budget.lower()
-        if budget_lower == "low":
-            parts.extend(
-                [
-                    "## RESEARCH DEPTH: SHALLOW (Quick Response)",
-                    "- Prioritize speed over completeness",
-                    "- If mental models or observations provide a reasonable answer, stop there",
-                    "- Only dig deeper if the initial results are clearly insufficient",
-                    "- Prefer a quick overview rather than exhaustive details",
-                    "- Answer promptly with available information",
-                    "",
-                ]
-            )
-        elif budget_lower == "mid":
-            parts.extend(
-                [
-                    "## RESEARCH DEPTH: MODERATE (Balanced)",
-                    "- Balance thoroughness with efficiency",
-                    "- Check multiple sources when the question warrants it",
-                    "- Verify stale data if it's central to the answer",
-                    "- Don't over-explore, but ensure reasonable coverage",
-                    "",
-                ]
-            )
-        elif budget_lower == "high":
-            parts.extend(
-                [
-                    "## RESEARCH DEPTH: DEEP (Thorough Exploration)",
-                    "- Explore comprehensively before answering",
-                    "- Search across all available knowledge levels",
-                    "- Use multiple query variations to ensure coverage",
-                    "- Verify information across different retrieval levels",
-                    "- Use expand() to get full context on important memories",
-                    "- Take time to synthesize a complete, well-researched answer",
-                    "",
-                ]
-            )
-
-    parts.append("## Workflow")
-
-    if has_mental_models:
-        parts.extend(
-            [
-                "1. First, try search_mental_models() - check if a curated summary exists",
-                "2. If no mental model or it's stale, try search_observations() for consolidated knowledge",
-                "3. If observations are stale OR you need specific details, use recall() for raw facts",
-                "4. Use expand() if you need more context on specific memories",
-                "5. When ready, call done() with your answer and supporting IDs",
-            ]
-        )
-    else:
-        parts.extend(
-            [
-                "1. First, try search_observations() - check for consolidated knowledge",
-                "2. If observations are stale OR you need specific details, use recall() for raw facts",
-                "3. Use expand() if you need more context on specific memories",
-                "4. When ready, call done() with your answer and supporting IDs",
-            ]
-        )
-
+    # Answer mode: include mental model lookup in workflow
     parts.extend(
         [
+            "1. Review the pre-fetched mental models for relevant synthesized knowledge",
+            "2. If relevant, call get_mental_model(model_id) for full observations",
+            "3. DECOMPOSE the question into component searches (see Query Strategy above)",
+            "   - Identify entities and concepts in the question",
+            "   - Search for each separately with targeted queries",
+            "4. Run multiple recall() calls - don't just echo the user's question",
+            "5. Use expand() if you need more context on specific memories",
+            "6. BEFORE answering: Check if any person/project/concept from the memories deserves a mental model - use learn() if so",
+            "7. When ready, call done() with your answer and supporting memory_ids",
+            "",
+            "## When to Use learn() - IMPORTANT",
+            "ACTIVELY look for opportunities to use learn() when you discover:",
+            "- A person mentioned in 2+ memories who has no mental model yet",
+            "- A project or concept the user asks about that has no mental model",
+            "- A pattern or topic worth tracking for future questions",
+            "",
+            "DO NOT wait to be asked - proactively create models when you see the need.",
+            "Example: learn(name='Project Alpha', description='Track goals, status, and key decisions for Project Alpha')",
             "",
             "## Output Format: Plain Text Answer",
             "Call done() with a plain text 'answer' field.",
             "- Do NOT use markdown formatting",
             "- NEVER include memory IDs, UUIDs, or 'Memory references' in the answer text",
-            "- Put IDs ONLY in the memory_ids/mental_model_ids/observation_ids arrays, not in the answer",
+            "- Put memory IDs ONLY in the memory_ids array parameter, not in the answer",
         ]
     )
 
@@ -398,10 +295,9 @@ def build_agent_prompt(
     else:
         parts.append(
             "\n## Instructions\n"
-            "Start by searching for relevant information using the hierarchical retrieval strategy:\n"
-            "1. Try search_mental_models() first for curated summaries\n"
-            "2. Try search_observations() for consolidated knowledge\n"
-            "3. Use recall() for specific details or to verify stale data"
+            "Start by calling list_mental_models() to see available mental models - they contain pre-synthesized knowledge. "
+            "If a relevant model exists, use get_mental_model(model_id) to get its observations. "
+            "Then use recall(query) for specific details not covered by mental models."
         )
 
     return "\n".join(parts)
@@ -481,3 +377,386 @@ Your approach:
 
 Only say "I don't have information" if the retrieved data is truly unrelated to the question.
 Do NOT fabricate information that has no basis in the retrieved data."""
+
+
+# =============================================================================
+# 4-Phase Mental Model Reflect Prompts
+# =============================================================================
+
+SEED_PHASE_SYSTEM_PROMPT = """You are analyzing memories to discover NEW patterns and generate candidate observations.
+
+Your task is to identify potential observations (beliefs, preferences, patterns, behaviors) that could be part of a mental model about this person/topic.
+
+## Important: Avoid Redundancy
+If existing observations are provided, DO NOT generate candidates that are essentially the same.
+Focus on discovering NEW patterns not already covered by existing observations.
+
+## Rules
+- Generate 5-15 candidate observations for NEW patterns only
+- Each candidate should be specific and testable (can be supported or contradicted by evidence)
+- Note which memory IDs inspired each candidate (these are seeds, not final evidence)
+- Focus on patterns that appear MULTIPLE TIMES across many memories - the more the better
+- The best candidates are ones you can find 10, 20, or even 50+ supporting memories for
+- Skip patterns that are already covered by existing observations
+
+## Output Format
+Return a JSON array of candidate observations:
+```json
+{
+  "candidates": [
+    {
+      "content": "The specific observation/belief/pattern - be detailed and specific",
+      "seed_memory_ids": ["memory_id_1", "memory_id_2", "memory_id_3"]
+    }
+  ]
+}
+```
+
+Focus on patterns that appear multiple times or have strong signals. Don't generate obvious or trivial observations.
+Prefer candidates with MORE seed memories - they're more likely to be real patterns.
+Return an empty candidates array if no genuinely new patterns are found."""
+
+
+def build_seed_phase_prompt(
+    memories: list[dict],
+    topic: str | None = None,
+    existing_observations: list[dict] | None = None,
+) -> str:
+    """Build the user prompt for the seed phase.
+
+    Args:
+        memories: List of memories to analyze
+        topic: Optional topic focus for the mental model
+        existing_observations: Optional list of existing observations to avoid rediscovering
+    """
+    parts = []
+
+    if topic:
+        parts.append(f"## Topic Focus\n{topic}\n")
+
+    # Include existing observations so we don't rediscover them
+    if existing_observations:
+        parts.append("## Existing Observations (DO NOT regenerate these)")
+        parts.append("These patterns are already tracked. Focus on discovering NEW patterns:\n")
+        for i, obs in enumerate(existing_observations, 1):
+            title = obs.get("title", "")
+            content = obs.get("content", "")
+            parts.append(f"{i}. **{title}**: {content}\n")
+        parts.append("")
+
+    parts.append("## Memories to Analyze")
+    parts.append("Review these memories and identify patterns, preferences, beliefs, and behaviors:\n")
+
+    for mem in memories:
+        mem_id = mem.get("id", "unknown")
+        content = mem.get("content", mem.get("text", ""))
+        timestamp = mem.get("timestamp", mem.get("created_at", ""))
+        parts.append(f"[{mem_id}] ({timestamp}): {content}\n")
+
+    parts.append("\n## Instructions")
+    if existing_observations:
+        parts.append("Generate candidate observations for NEW patterns not already covered above.")
+        parts.append("If all patterns are already covered by existing observations, return an empty candidates array.")
+    else:
+        parts.append("Generate candidate observations based on patterns you see in these memories.")
+    parts.append("Look for: recurring themes, stated preferences, behavioral patterns, beliefs, values, goals.")
+
+    return "\n".join(parts)
+
+
+VALIDATE_PHASE_SYSTEM_PROMPT = """You are validating candidate observations against evidence.
+
+For each candidate, you have:
+- Supporting memories (evidence FOR the observation)
+- Contradicting memories (evidence AGAINST the observation)
+
+## Your Task
+1. Evaluate each candidate based on the evidence
+2. For valid candidates, extract EXACT QUOTES from supporting memories
+3. Discard candidates with insufficient or contradicting evidence
+4. Merge similar candidates into single, refined observations
+
+## Rules for Quotes
+- Quotes must be EXACT text from the memory, not paraphrased
+- Each quote should directly support the observation
+- The MORE evidence quotes, the BETTER - don't limit yourself, include ALL relevant quotes (10, 20, 50+)
+- Observations with only 1-2 quotes are weak and should be discarded unless the evidence is exceptionally strong
+- Stronger observations have more supporting evidence - aim for comprehensive coverage
+
+## Output Format
+Return validated observations with evidence:
+```json
+{
+  "observations": [
+    {
+      "title": "Short descriptive title (3-8 words) - like a headline",
+      "content": "The full observation content - detailed explanation of the pattern/belief",
+      "evidence": [
+        {
+          "memory_id": "exact_memory_id",
+          "quote": "Exact quote from the memory text",
+          "relevance": "Brief explanation of how this supports the observation",
+          "timestamp": "2024-01-15T10:00:00Z"
+        }
+      ]
+    }
+  ],
+  "discarded": [
+    {
+      "content": "The discarded candidate",
+      "reason": "Why it was discarded (insufficient evidence, contradicted, etc.)"
+    }
+  ],
+  "merged": [
+    {
+      "from": ["candidate 1 content", "candidate 2 content"],
+      "into": "The merged observation content"
+    }
+  ]
+}
+```
+
+## Title Guidelines
+- Title should be a SHORT label (like "Prefers morning meetings" or "Coffee enthusiast")
+- NOT a truncated version of the content
+- Think of it as a category/tag for the observation
+
+Be rigorous: only keep observations with clear, verifiable evidence from multiple memories."""
+
+
+def build_validate_phase_prompt(candidates_with_evidence: list[dict]) -> str:
+    """Build the user prompt for the validate phase."""
+    parts = ["## Candidates to Validate\n"]
+
+    for i, item in enumerate(candidates_with_evidence, 1):
+        candidate = item.get("candidate", {})
+        supporting = item.get("supporting_memories", [])
+        contradicting = item.get("contradicting_memories", [])
+
+        parts.append(f"### Candidate {i}: {candidate.get('content', '')}")
+
+        if supporting:
+            parts.append("\n**Supporting Evidence:**")
+            for mem in supporting:
+                mem_id = mem.get("id", "unknown")
+                content = mem.get("content", mem.get("text", ""))
+                timestamp = mem.get("timestamp", mem.get("created_at", ""))
+                parts.append(f"- [{mem_id}] ({timestamp}): {content}")
+
+        if contradicting:
+            parts.append("\n**Contradicting Evidence:**")
+            for mem in contradicting:
+                mem_id = mem.get("id", "unknown")
+                content = mem.get("content", mem.get("text", ""))
+                timestamp = mem.get("timestamp", mem.get("created_at", ""))
+                parts.append(f"- [{mem_id}] ({timestamp}): {content}")
+
+        if not supporting and not contradicting:
+            parts.append("\n*No additional evidence found*")
+
+        parts.append("")
+
+    parts.append("## Instructions")
+    parts.append("1. Evaluate each candidate based on its evidence")
+    parts.append("2. Keep candidates with strong supporting evidence")
+    parts.append("3. Discard candidates with no evidence or strong contradictions")
+    parts.append("4. Merge similar candidates")
+    parts.append("5. Extract EXACT quotes (copy-paste from memory text) for evidence")
+
+    return "\n".join(parts)
+
+
+COMPARE_PHASE_SYSTEM_PROMPT = """You are merging new observations with an existing mental model.
+
+You have:
+- EXISTING observations (from the current mental model)
+- NEW observations (from this reflect cycle)
+
+## Your Task
+Produce the final, complete mental model by:
+1. Keeping existing observations that are still valid
+2. Updating existing observations with new evidence (ADD new evidence to existing)
+3. Adding new observations that don't overlap with existing
+4. Removing existing observations that are contradicted by new evidence
+5. Merging overlapping observations
+
+## Rules
+- The final model should have no contradictions
+- Each observation must have evidence with exact quotes
+- COMBINE evidence from both existing and new observations
+- If an existing observation has new supporting evidence, ADD ALL the new evidence to it
+- Include ALL relevant evidence - the more quotes the better (10, 20, 50+ is great)
+- Observations with more evidence are more reliable - don't limit the number of quotes
+
+## Output Format
+Return the complete, final mental model:
+```json
+{
+  "observations": [
+    {
+      "title": "Short descriptive title (3-8 words)",
+      "content": "Full observation content - detailed explanation",
+      "evidence": [
+        {
+          "memory_id": "id",
+          "quote": "exact quote",
+          "relevance": "explanation",
+          "timestamp": "ISO timestamp"
+        }
+      ],
+      "created_at": "ISO timestamp of when observation was first created"
+    }
+  ],
+  "changes": {
+    "kept": ["Observation that was kept unchanged"],
+    "updated": [{"from": "old content", "to": "new content", "reason": "why"}],
+    "added": ["New observation that was added"],
+    "removed": [{"content": "removed observation", "reason": "why removed"}],
+    "merged": [{"from": ["obs1", "obs2"], "into": "merged observation"}]
+  }
+}
+```"""
+
+
+def build_compare_phase_prompt(
+    existing_observations: list[dict],
+    new_observations: list[dict],
+) -> str:
+    """Build the user prompt for the compare phase."""
+    parts = []
+
+    parts.append("## Existing Mental Model Observations")
+    if existing_observations:
+        for i, obs in enumerate(existing_observations, 1):
+            title = obs.get("title", "")
+            content = obs.get("content", obs.get("text", ""))
+            evidence = obs.get("evidence", [])
+            parts.append(f"\n### Existing {i}: {title}")
+            parts.append(f"Content: {content}")
+            if evidence:
+                parts.append(f"Evidence ({len(evidence)} items):")
+                for ev in evidence[:5]:  # Show max 5 evidence items
+                    parts.append(f'  - [{ev.get("memory_id", "?")}]: "{ev.get("quote", "")}"')
+                if len(evidence) > 5:
+                    parts.append(f"  ... and {len(evidence) - 5} more")
+    else:
+        parts.append("*No existing observations*")
+
+    parts.append("\n## New Observations from This Reflect")
+    if new_observations:
+        for i, obs in enumerate(new_observations, 1):
+            title = obs.get("title", "")
+            content = obs.get("content", "")
+            evidence = obs.get("evidence", [])
+            parts.append(f"\n### New {i}: {title}")
+            parts.append(f"Content: {content}")
+            if evidence:
+                parts.append(f"Evidence ({len(evidence)} items):")
+                for ev in evidence:
+                    parts.append(f'  - [{ev.get("memory_id", "?")}]: "{ev.get("quote", "")}"')
+    else:
+        parts.append("*No new observations*")
+
+    parts.append("\n## Instructions")
+    parts.append("Merge these into a coherent, non-contradictory mental model.")
+    parts.append("Preserve all valid evidence. Remove stale or contradicted observations.")
+
+    return "\n".join(parts)
+
+
+# =============================================================================
+# UPDATE EXISTING Phase Prompts (for diff-based refresh)
+# =============================================================================
+
+UPDATE_EXISTING_SYSTEM_PROMPT = """You are updating existing observations with newly found evidence.
+
+For each existing observation, you have been given:
+- The original observation (title, content, existing evidence)
+- Newly found supporting memories
+- Newly found contradicting memories
+
+## Your Task
+1. Extract EXACT QUOTES from new supporting memories to add to the observation
+2. Flag observations with strong contradicting evidence for potential removal
+3. Keep existing evidence intact - only ADD new evidence
+
+## Rules for Quotes
+- Quotes must be EXACT text from the memory, not paraphrased
+- Each quote should directly support the observation
+- Include ALL relevant quotes from the new memories
+
+## Output Format
+Return updated observations with new evidence:
+```json
+{
+  "updated_observations": [
+    {
+      "title": "Original title",
+      "content": "Original content",
+      "existing_evidence_count": 5,
+      "new_evidence": [
+        {
+          "memory_id": "exact_memory_id",
+          "quote": "Exact quote from the memory text",
+          "relevance": "Brief explanation of how this supports the observation",
+          "timestamp": "2024-01-15T10:00:00Z"
+        }
+      ],
+      "has_contradiction": false,
+      "contradiction_note": null
+    }
+  ]
+}
+```
+
+If an observation has strong contradicting evidence, set has_contradiction=true and explain in contradiction_note."""
+
+
+def build_update_existing_prompt(observations_with_evidence: list[dict]) -> str:
+    """Build the user prompt for the update existing phase.
+
+    Args:
+        observations_with_evidence: List of existing observations with new evidence found
+    """
+    parts = ["## Existing Observations to Update\n"]
+
+    for i, item in enumerate(observations_with_evidence, 1):
+        obs = item.get("observation", {})
+        supporting = item.get("supporting_memories", [])
+        contradicting = item.get("contradicting_memories", [])
+
+        title = obs.get("title", "")
+        content = obs.get("content", "")
+        existing_evidence = obs.get("evidence", [])
+
+        parts.append(f"### Observation {i}: {title}")
+        parts.append(f"Content: {content}")
+        parts.append(f"Existing evidence count: {len(existing_evidence)}")
+
+        if supporting:
+            parts.append("\n**New Supporting Memories:**")
+            for mem in supporting:
+                mem_id = mem.get("id", "unknown")
+                mem_content = mem.get("content", mem.get("text", ""))
+                timestamp = mem.get("timestamp", mem.get("created_at", ""))
+                parts.append(f"- [{mem_id}] ({timestamp}): {mem_content}")
+
+        if contradicting:
+            parts.append("\n**New Contradicting Memories:**")
+            for mem in contradicting:
+                mem_id = mem.get("id", "unknown")
+                mem_content = mem.get("content", mem.get("text", ""))
+                timestamp = mem.get("timestamp", mem.get("created_at", ""))
+                parts.append(f"- [{mem_id}] ({timestamp}): {mem_content}")
+
+        if not supporting and not contradicting:
+            parts.append("\n*No new evidence found*")
+
+        parts.append("")
+
+    parts.append("## Instructions")
+    parts.append("1. Extract EXACT quotes from new supporting memories")
+    parts.append("2. Flag observations with strong contradictions")
+    parts.append("3. Return the updated observations with new evidence added")
+
+    return "\n".join(parts)

hindsight-api/hindsight_api/engine/reflect/tools.py

@@ -1,17 +1,16 @@
 """
 Tool implementations for the reflect agent.
-
-Implements hierarchical retrieval:
-1. search_mental_models - User-curated stored reflect responses (highest quality)
-2. search_observations - Consolidated knowledge with freshness
-3. recall - Raw facts as ground truth
 """
 
 import logging
+import re
 import uuid
-from datetime import datetime, timedelta, timezone
+from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any
 
+from .models import MentalModelInput
+from .observations import Observation, ObservationEvidence, Trend
+
 if TYPE_CHECKING:
     from asyncpg import Connection
 
@@ -20,215 +19,156 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-# Observation is considered stale if not updated in this many days
-STALE_THRESHOLD_DAYS = 7
+
+def generate_model_id(name: str) -> str:
+    """Generate a stable ID from mental model name."""
+    # Normalize: lowercase, replace spaces/special chars with hyphens
+    normalized = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+    # Truncate to reasonable length
+    return normalized[:50]
 
 
-async def tool_search_mental_models(
+def _parse_observations(observations_raw: list) -> list[Observation]:
+    """Parse raw observation dicts into typed Observation models."""
+    observations: list[Observation] = []
+    for obs in observations_raw:
+        if not isinstance(obs, dict):
+            continue
+
+        try:
+            parsed = Observation(
+                title=obs.get("title", ""),
+                content=obs.get("content", ""),
+                evidence=[
+                    ObservationEvidence(
+                        memory_id=ev.get("memory_id", ""),
+                        quote=ev.get("quote", ""),
+                        relevance=ev.get("relevance", ""),
+                        timestamp=ev.get("timestamp"),
+                    )
+                    for ev in obs.get("evidence", [])
+                    if isinstance(ev, dict)
+                ],
+                created_at=obs.get("created_at"),
+            )
+            observations.append(parsed)
+        except Exception as e:
+            logger.warning(f"Failed to parse observation: {e}")
+            continue
+
+    return observations
+
+
+async def tool_lookup(
     conn: "Connection",
     bank_id: str,
-    query: str,
-    query_embedding: list[float],
-    max_results: int = 5,
+    model_id: str | None = None,
     tags: list[str] | None = None,
     tags_match: str = "any",
-    exclude_ids: list[str] | None = None,
 ) -> dict[str, Any]:
     """
-    Search user-curated mental models by semantic similarity.
-
-    Mental models are high-quality, manually created summaries about specific topics.
-    They should be searched FIRST as they represent the most reliable synthesized knowledge.
+    List or get mental models.
 
     Args:
         conn: Database connection
         bank_id: Bank identifier
-        query: Search query (for logging/tracing)
-        query_embedding: Pre-computed embedding for semantic search
-        max_results: Maximum number of mental models to return
-        tags: Optional tags to filter mental models
+        model_id: Optional specific model ID to get (if None, lists all)
+        tags: Optional tags to filter models (when listing)
         tags_match: How to match tags - "any" (OR), "all" (AND)
-        exclude_ids: Optional list of mental model IDs to exclude (e.g., when refreshing a mental model)
 
     Returns:
-        Dict with matching mental models including content and freshness info
+        Dict with either a list of models or a single model's details
     """
-    from ..memory_engine import fq_table
-
-    # Build filters dynamically
-    filters = ""
-    params: list[Any] = [bank_id, str(query_embedding), max_results]
-    next_param = 4
-
-    if tags:
-        if tags_match == "all":
-            filters += f" AND tags @> ${next_param}::varchar[]"
-        else:
-            filters += f" AND (tags && ${next_param}::varchar[] OR tags IS NULL OR tags = '{{}}')"
-        params.append(tags)
-        next_param += 1
-
-    if exclude_ids:
-        filters += f" AND id != ALL(${next_param}::uuid[])"
-        params.append(exclude_ids)
-        next_param += 1
-
-    # Search mental models by embedding similarity
-    rows = await conn.fetch(
-        f"""
-        SELECT
-            id, name, content,
-            tags, created_at, last_refreshed_at,
-            1 - (embedding <=> $2::vector) as relevance
-        FROM {fq_table("mental_models")}
-        WHERE bank_id = $1 AND embedding IS NOT NULL {filters}
-        ORDER BY embedding <=> $2::vector
-        LIMIT $3
-        """,
-        *params,
-    )
-
-    now = datetime.now(timezone.utc)
-    mental_models = []
-
-    for row in rows:
-        last_refreshed_at = row["last_refreshed_at"]
-        if last_refreshed_at and last_refreshed_at.tzinfo is None:
-            last_refreshed_at = last_refreshed_at.replace(tzinfo=timezone.utc)
-
-        # Calculate freshness
-        is_stale = False
-        if last_refreshed_at:
-            age = now - last_refreshed_at
-            is_stale = age > timedelta(days=STALE_THRESHOLD_DAYS)
-
-        mental_models.append(
-            {
-                "id": str(row["id"]),
-                "name": row["name"],
-                "content": row["content"],
-                "tags": row["tags"] or [],
-                "relevance": round(row["relevance"], 4),
-                "updated_at": last_refreshed_at.isoformat() if last_refreshed_at else None,
-                "is_stale": is_stale,
-            }
+    if model_id:
+        # Get specific mental model with full details including observations
+        row = await conn.fetchrow(
+            """
+            SELECT id, subtype, name, description, observations, entity_id, last_updated
+            FROM mental_models
+            WHERE id = $1 AND bank_id = $2
+            """,
+            model_id,
+            bank_id,
         )
+        if row:
+            # Parse observations JSON
+            obs_data = row["observations"] or {"observations": []}
+            if isinstance(obs_data, str):
+                import json
 
-    return {
-        "query": query,
-        "count": len(mental_models),
-        "mental_models": mental_models,
-    }
+                obs_data = json.loads(obs_data)
+            observations_raw = obs_data.get("observations", []) if isinstance(obs_data, dict) else obs_data
 
+            # Parse observations into typed models
+            observations = _parse_observations(observations_raw)
 
-async def tool_search_observations(
-    memory_engine: "MemoryEngine",
-    bank_id: str,
-    query: str,
-    request_context: "RequestContext",
-    max_tokens: int = 5000,
-    tags: list[str] | None = None,
-    tags_match: str = "any",
-    last_consolidated_at: datetime | None = None,
-    pending_consolidation: int = 0,
-) -> dict[str, Any]:
-    """
-    Search consolidated observations using recall with include_observations.
-
-    Observations are auto-generated from memories. Returns freshness info
-    so the agent knows if it should also verify with recall().
-
-    Args:
-        memory_engine: Memory engine instance
-        bank_id: Bank identifier
-        query: Search query
-        request_context: Request context for authentication
-        max_tokens: Maximum tokens for results (default 5000)
-        tags: Optional tags to filter observations
-        tags_match: How to match tags - "any" (OR), "all" (AND)
-        last_consolidated_at: When consolidation last ran (for staleness check)
-        pending_consolidation: Number of memories waiting to be consolidated
-
-    Returns:
-        Dict with matching observations including freshness info
-    """
-    from ..memory_engine import fq_table
-
-    # Use recall to search observations (they come back in results field when fact_type=["observation"])
-    result = await memory_engine.recall_async(
-        bank_id=bank_id,
-        query=query,
-        fact_type=["observation"],  # Only retrieve observations
-        max_tokens=max_tokens,  # Token budget controls how many observations are returned
-        enable_trace=False,
-        request_context=request_context,
-        tags=tags,
-        tags_match=tags_match,
-        _connection_budget=1,
-        _quiet=True,
-    )
-
-    observations = []
-
-    # When fact_type=["observation"], results come back in `results` field as MemoryFact objects
-    # We need to fetch additional fields (proof_count, source_memory_ids) from the database
-    if result.results:
-        obs_ids = [m.id for m in result.results]
-
-        # Fetch proof_count and source_memory_ids for these observations
-        pool = await memory_engine._get_pool()
-        async with pool.acquire() as conn:
-            obs_rows = await conn.fetch(
-                f"""
-                SELECT id, proof_count, source_memory_ids
-                FROM {fq_table("memory_units")}
-                WHERE id = ANY($1::uuid[])
-                """,
-                obs_ids,
-            )
-            obs_data = {str(row["id"]): row for row in obs_rows}
-
-        for m in result.results:
-            # Get additional data from DB lookup
-            extra = obs_data.get(m.id, {})
-            proof_count = extra.get("proof_count", 1) if extra else 1
-            source_ids = extra.get("source_memory_ids", []) if extra else []
-            # Convert UUIDs to strings
-            source_memory_ids = [str(sid) for sid in (source_ids or [])]
-
-            # Determine staleness
-            is_stale = False
-            staleness_reason = None
-            if pending_consolidation > 0:
-                is_stale = True
-                staleness_reason = f"{pending_consolidation} memories pending consolidation"
-
-            observations.append(
-                {
-                    "id": str(m.id),
-                    "text": m.text,
-                    "proof_count": proof_count,
-                    "source_memory_ids": source_memory_ids,
-                    "tags": m.tags or [],
-                    "is_stale": is_stale,
-                    "staleness_reason": staleness_reason,
-                }
-            )
-
-    # Return freshness info (more understandable than raw pending_consolidation count)
-    if pending_consolidation == 0:
-        freshness = "up_to_date"
-    elif pending_consolidation < 10:
-        freshness = "slightly_stale"
+            return {
+                "found": True,
+                "model": {
+                    "id": row["id"],
+                    "subtype": row["subtype"],
+                    "name": row["name"],
+                    "description": row["description"],
+                    "observations": observations,
+                    "entity_id": str(row["entity_id"]) if row["entity_id"] else None,
+                    "last_updated": row["last_updated"].isoformat() if row["last_updated"] else None,
+                },
+            }
+        return {"found": False, "model_id": model_id}
     else:
-        freshness = "stale"
+        # List mental models (compact: id, name, description only)
+        # Full observations are retrieved via get_mental_model(model_id)
+        # NOTE: Directives (subtype='directive') are excluded from listing -
+        # they are injected into the system prompt, not discoverable via tools
+        # Filter by tags if provided
+        if tags:
+            if tags_match == "all":
+                # All tags must match
+                rows = await conn.fetch(
+                    """
+                    SELECT id, subtype, name, description
+                    FROM mental_models
+                    WHERE bank_id = $1 AND tags @> $2::varchar[] AND subtype != 'directive'
+                    ORDER BY last_updated DESC NULLS LAST, created_at DESC
+                    """,
+                    bank_id,
+                    tags,
+                )
+            else:
+                # Any tag matches (OR) - default
+                rows = await conn.fetch(
+                    """
+                    SELECT id, subtype, name, description
+                    FROM mental_models
+                    WHERE bank_id = $1 AND tags && $2::varchar[] AND subtype != 'directive'
+                    ORDER BY last_updated DESC NULLS LAST, created_at DESC
+                    """,
+                    bank_id,
+                    tags,
+                )
+        else:
+            rows = await conn.fetch(
+                """
+                SELECT id, subtype, name, description
+                FROM mental_models
+                WHERE bank_id = $1 AND subtype != 'directive'
+                ORDER BY last_updated DESC NULLS LAST, created_at DESC
+                """,
+                bank_id,
+            )
 
-    return {
-        "query": query,
-        "count": len(observations),
-        "observations": observations,
-        "freshness": freshness,
-    }
+        return {
+            "count": len(rows),
+            "models": [
+                {
+                    "id": row["id"],
+                    "subtype": row["subtype"],
+                    "name": row["name"],
+                    "description": row["description"],
+                }
+                for row in rows
+            ],
+        }
 
 
 async def tool_recall(
@@ -245,9 +185,6 @@ async def tool_recall(
     """
     Search memories using TEMPR retrieval.
 
-    This is the ground truth - raw facts and experiences.
-    Use when mental models/observations don't exist, are stale, or need verification.
-
     Args:
         memory_engine: Memory engine instance
         bank_id: Bank identifier
@@ -265,14 +202,13 @@ async def tool_recall(
     result = await memory_engine.recall_async(
         bank_id=bank_id,
         query=query,
-        fact_type=["experience", "world"],  # Exclude opinions and observations
+        fact_type=["experience", "world"],  # Exclude opinions
         max_tokens=max_tokens,
         enable_trace=False,
         request_context=request_context,
         tags=tags,
         tags_match=tags_match,
         _connection_budget=connection_budget,
-        _quiet=True,  # Suppress logging for internal operations
     )
 
     memories = []
@@ -294,6 +230,85 @@ async def tool_recall(
     }
 
 
+async def tool_learn(
+    conn: "Connection",
+    bank_id: str,
+    input: MentalModelInput,
+    tags: list[str] | None = None,
+) -> dict[str, Any]:
+    """
+    Create a mental model placeholder with subtype='learned'.
+
+    The agent only specifies name and description - actual observations are generated
+    in the background via refresh, similar to pinned models.
+
+    Args:
+        conn: Database connection
+        bank_id: Bank identifier
+        input: Mental model input data (name, description, optional entity_id)
+        tags: Tags to apply to new mental models (from reflect context)
+
+    Returns:
+        Dict with created model info including model_id for background generation
+    """
+    model_id = generate_model_id(input.name)
+
+    # Parse entity_id if provided
+    entity_uuid = None
+    if input.entity_id:
+        try:
+            entity_uuid = uuid.UUID(input.entity_id)
+        except ValueError:
+            logger.warning(f"Invalid entity_id format: {input.entity_id}")
+
+    # Check if model exists
+    existing = await conn.fetchrow(
+        "SELECT id FROM mental_models WHERE id = $1 AND bank_id = $2",
+        model_id,
+        bank_id,
+    )
+
+    if existing:
+        # Update description only - observations will be regenerated
+        await conn.execute(
+            """
+            UPDATE mental_models SET
+                description = $3,
+                entity_id = $4
+            WHERE id = $1 AND bank_id = $2
+            """,
+            model_id,
+            bank_id,
+            input.description,
+            entity_uuid,
+        )
+        status = "updated"
+    else:
+        # Insert new model placeholder - observations will be generated in background
+        await conn.execute(
+            """
+            INSERT INTO mental_models (id, bank_id, subtype, name, description, observations, entity_id, tags, created_at)
+            VALUES ($1, $2, 'learned', $3, $4, '{}'::jsonb, $5, $6, NOW())
+            """,
+            model_id,
+            bank_id,
+            input.name,
+            input.description,
+            entity_uuid,
+            tags or [],
+        )
+        status = "created"
+
+    logger.info(f"[REFLECT] Mental model '{model_id}' {status} in bank {bank_id} - pending background generation")
+
+    return {
+        "status": status,
+        "model_id": model_id,
+        "name": input.name,
+        "pending_generation": True,
+    }
+
+
 async def tool_expand(
     conn: "Connection",
     bank_id: str,
@@ -312,8 +327,6 @@ async def tool_expand(
     Returns:
         Dict with results array, each containing memory, chunk, and optionally document data
     """
-    from ..memory_engine import fq_table
-
     if not memory_ids:
         return {"error": "memory_ids is required and must not be empty"}
 
@@ -331,9 +344,9 @@ async def tool_expand(
 
     # Batch fetch all memory units
     memories = await conn.fetch(
-        f"""
+        """
         SELECT id, text, chunk_id, document_id, fact_type, context
-        FROM {fq_table("memory_units")}
+        FROM memory_units
         WHERE id = ANY($1) AND bank_id = $2
         """,
         valid_uuids,
@@ -350,9 +363,9 @@ async def tool_expand(
     chunk_map: dict[str, Any] = {}
     if chunk_ids:
         chunks = await conn.fetch(
-            f"""
+            """
             SELECT chunk_id, chunk_text, chunk_index, document_id
-            FROM {fq_table("chunks")}
+            FROM chunks
             WHERE chunk_id = ANY($1)
             """,
             chunk_ids,
@@ -372,9 +385,9 @@ async def tool_expand(
     all_doc_ids = list(doc_ids_from_chunks | doc_ids_direct)
     if all_doc_ids:
         docs = await conn.fetch(
-            f"""
+            """
             SELECT id, original_text, metadata, retain_params
-            FROM {fq_table("documents")}
+            FROM documents
             WHERE id = ANY($1) AND bank_id = $2
             """,
             all_doc_ids,

hindsight-api/hindsight_api/engine/reflect/tools_schema.py

@@ -2,70 +2,36 @@
 Tool schema definitions for the reflect agent.
 
 These are OpenAI-format tool definitions used with native tool calling.
-The reflect agent uses a hierarchical retrieval strategy:
-1. search_mental_models - User-curated stored reflect responses (highest quality, if applicable)
-2. search_observations - Consolidated knowledge with freshness awareness
-3. recall - Raw facts (world/experience) as ground truth fallback
 """
 
 # Tool definitions in OpenAI format
-
-TOOL_SEARCH_MENTAL_MODELS = {
+TOOL_LIST_MENTAL_MODELS = {
     "type": "function",
     "function": {
-        "name": "search_mental_models",
-        "description": (
-            "Search user-curated mental models (stored reflect responses). These are high-quality, manually created "
-            "summaries about specific topics. Use FIRST when the question might be covered by an "
-            "existing mental model. Returns mental models with their content and last refresh time."
-        ),
+        "name": "list_mental_models",
+        "description": "List all available mental models - your synthesized knowledge about entities, concepts, and events. Returns an array of models with id, name, and description.",
         "parameters": {
             "type": "object",
-            "properties": {
-                "reason": {
-                    "type": "string",
-                    "description": "Brief explanation of why you're making this search (for debugging)",
-                },
-                "query": {
-                    "type": "string",
-                    "description": "Search query to find relevant mental models",
-                },
-                "max_results": {
-                    "type": "integer",
-                    "description": "Maximum number of mental models to return (default 5)",
-                },
-            },
-            "required": ["reason", "query"],
+            "properties": {},
+            "required": [],
         },
     },
 }
 
-TOOL_SEARCH_OBSERVATIONS = {
+TOOL_GET_MENTAL_MODEL = {
     "type": "function",
     "function": {
-        "name": "search_observations",
-        "description": (
-            "Search consolidated observations (auto-generated knowledge). These are automatically "
-            "synthesized from memories. Returns observations with freshness info (updated_at, is_stale). "
-            "If an observation is STALE, you should ALSO use recall() to verify with current facts."
-        ),
+        "name": "get_mental_model",
+        "description": "Get full details of a specific mental model including all observations and memory references.",
         "parameters": {
             "type": "object",
             "properties": {
-                "reason": {
+                "model_id": {
                     "type": "string",
-                    "description": "Brief explanation of why you're making this search (for debugging)",
-                },
-                "query": {
-                    "type": "string",
-                    "description": "Search query to find relevant observations",
-                },
-                "max_tokens": {
-                    "type": "integer",
-                    "description": "Maximum tokens for results (default 5000). Use higher values for broader searches.",
+                    "description": "ID of the mental model (from list_mental_models results)",
                 },
             },
-            "required": ["reason", "query"],
+            "required": ["model_id"],
         },
     },
 }
@@ -74,19 +40,10 @@ TOOL_RECALL = {
     "type": "function",
     "function": {
         "name": "recall",
-        "description": (
-            "Search raw memories (facts and experiences). This is the ground truth data. "
-            "Use when: (1) no reflections/mental models exist, (2) mental models are stale, "
-            "(3) you need specific details not in synthesized knowledge. "
-            "Returns individual memory facts with their timestamps."
-        ),
+        "description": "Search memories using semantic + temporal retrieval. Returns relevant memories from experience and world knowledge, each with an 'id' you can reference.",
         "parameters": {
             "type": "object",
             "properties": {
-                "reason": {
-                    "type": "string",
-                    "description": "Brief explanation of why you're making this search (for debugging)",
-                },
                 "query": {
                     "type": "string",
                     "description": "Search query string",
@@ -96,7 +53,29 @@ TOOL_RECALL = {
                     "description": "Optional limit on result size (default 2048). Use higher values for broader searches.",
                 },
             },
-            "required": ["reason", "query"],
+            "required": ["query"],
+        },
+    },
+}
+
+TOOL_LEARN = {
+    "type": "function",
+    "function": {
+        "name": "learn",
+        "description": "Create a new mental model to track an important recurring topic. Use when you discover a person, project, concept, or pattern that appears frequently and would benefit from synthesized knowledge. The model content will be generated automatically.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Human-readable name (e.g., 'Project Alpha', 'John Smith', 'Product Strategy')",
+                },
+                "description": {
+                    "type": "string",
+                    "description": "What to track and synthesize (e.g., 'Track goals, milestones, blockers, and key decisions for Project Alpha')",
+                },
+            },
+            "required": ["name", "description"],
         },
     },
 }
@@ -109,10 +88,6 @@ TOOL_EXPAND = {
         "parameters": {
             "type": "object",
             "properties": {
-                "reason": {
-                    "type": "string",
-                    "description": "Brief explanation of why you need more context (for debugging)",
-                },
                 "memory_ids": {
                     "type": "array",
                     "items": {"type": "string"},
@@ -124,7 +99,7 @@ TOOL_EXPAND = {
                     "description": "chunk: surrounding text chunk, document: full source document",
                 },
             },
-            "required": ["reason", "memory_ids", "depth"],
+            "required": ["memory_ids", "depth"],
         },
     },
 }
@@ -146,16 +121,11 @@ TOOL_DONE_ANSWER = {
                     "items": {"type": "string"},
                     "description": "Array of memory IDs that support your answer (put IDs here, NOT in answer text)",
                 },
-                "mental_model_ids": {
+                "model_ids": {
                     "type": "array",
                     "items": {"type": "string"},
                     "description": "Array of mental model IDs that support your answer",
                 },
-                "observation_ids": {
-                    "type": "array",
-                    "items": {"type": "string"},
-                    "description": "Array of observation IDs that support your answer",
-                },
             },
             "required": ["answer"],
         },
@@ -173,6 +143,8 @@ def _build_done_tool_with_directives(directive_rules: list[str]) -> dict:
     Args:
         directive_rules: List of directive rule strings
     """
+    from typing import Any, cast
+
     # Build rules list for description
     rules_list = "\n".join(f"  {i + 1}. {rule}" for i, rule in enumerate(directive_rules))
 
@@ -197,16 +169,11 @@ def _build_done_tool_with_directives(directive_rules: list[str]) -> dict:
                         "items": {"type": "string"},
                         "description": "Array of memory IDs that support your answer (put IDs here, NOT in answer text)",
                     },
-                    "mental_model_ids": {
+                    "model_ids": {
                         "type": "array",
                         "items": {"type": "string"},
                         "description": "Array of mental model IDs that support your answer",
                     },
-                    "observation_ids": {
-                        "type": "array",
-                        "items": {"type": "string"},
-                        "description": "Array of observation IDs that support your answer",
-                    },
                     "directive_compliance": {
                         "type": "string",
                         "description": f"REQUIRED: Confirm your answer complies with ALL directives. List each directive and how your answer follows it:\n{rules_list}\n\nFormat: 'Directive 1: [how answer complies]. Directive 2: [how answer complies]...'",
@@ -218,28 +185,29 @@ def _build_done_tool_with_directives(directive_rules: list[str]) -> dict:
     }
 
 
-def get_reflect_tools(directive_rules: list[str] | None = None) -> list[dict]:
+def get_reflect_tools(enable_learn: bool = True, directive_rules: list[str] | None = None) -> list[dict]:
     """
     Get the list of tools for the reflect agent.
 
-    The tools support a hierarchical retrieval strategy:
-    1. search_mental_models - User-curated stored reflect responses (try first)
-    2. search_observations - Consolidated knowledge with freshness
-    3. recall - Raw facts as ground truth
-
     Args:
+        enable_learn: Whether to include the learn tool
         directive_rules: Optional list of directive rule strings. If provided,
                         the done() tool will require directive compliance confirmation.
 
     Returns:
         List of tool definitions in OpenAI format
     """
-    tools = [
-        TOOL_SEARCH_MENTAL_MODELS,
-        TOOL_SEARCH_OBSERVATIONS,
-        TOOL_RECALL,
-        TOOL_EXPAND,
-    ]
+    tools = []
+
+    # Include mental model tools for lookup
+    tools.append(TOOL_LIST_MENTAL_MODELS)
+    tools.append(TOOL_GET_MENTAL_MODEL)
+    tools.append(TOOL_RECALL)
+
+    if enable_learn:
+        tools.append(TOOL_LEARN)
+
+    tools.append(TOOL_EXPAND)
 
     # Use directive-aware done tool if directives are present
     if directive_rules:

hindsight-api/hindsight_api/engine/response_models.py

@@ -10,8 +10,8 @@ from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field
 
-# Valid fact types for recall operations (excludes 'opinion' which is deprecated)
-VALID_RECALL_FACT_TYPES = frozenset(["world", "experience", "observation"])
+# Valid fact types for recall operations (excludes 'observation' which is internal, and 'opinion' which is deprecated)
+VALID_RECALL_FACT_TYPES = frozenset(["world", "experience"])
 
 
 class LLMToolCall(BaseModel):
@@ -28,15 +28,12 @@ class LLMToolCallResult(BaseModel):
     content: str | None = Field(default=None, description="Text content if any")
     tool_calls: list[LLMToolCall] = Field(default_factory=list, description="Tool calls requested by the LLM")
     finish_reason: str | None = Field(default=None, description="Reason the LLM stopped: 'stop', 'tool_calls', etc.")
-    input_tokens: int = Field(default=0, description="Input tokens used in this call")
-    output_tokens: int = Field(default=0, description="Output tokens used in this call")
 
 
 class ToolCallTrace(BaseModel):
     """A single tool call made during reflect."""
 
     tool: str = Field(description="Tool name: lookup, recall, learn, expand")
-    reason: str | None = Field(default=None, description="Agent's reasoning for making this tool call")
     input: dict = Field(description="Tool input parameters")
     output: dict = Field(description="Tool output/result")
     duration_ms: int = Field(description="Execution time in milliseconds")
@@ -50,13 +47,13 @@ class LLMCallTrace(BaseModel):
     duration_ms: int = Field(description="Execution time in milliseconds")
 
 
-class ObservationRef(BaseModel):
-    """Reference to an observation accessed during reflect."""
+class MentalModelRef(BaseModel):
+    """Reference to a mental model accessed during reflect."""
 
-    id: str = Field(description="Observation ID")
-    name: str = Field(description="Observation name")
-    type: str = Field(description="Observation type: entity, concept, event")
-    subtype: str = Field(description="Observation subtype: structural, emergent, learned")
+    id: str = Field(description="Mental model ID")
+    name: str = Field(description="Mental model name")
+    type: str = Field(description="Mental model type: entity, concept, event")
+    subtype: str = Field(description="Mental model subtype: structural, emergent, learned")
     description: str = Field(description="Brief description")
     summary: str | None = Field(default=None, description="Full summary (when looked up in detail)")
 
@@ -66,7 +63,7 @@ class DirectiveRef(BaseModel):
 
     id: str = Field(description="Directive mental model ID")
     name: str = Field(description="Directive name")
-    content: str = Field(description="Directive content")
+    rules: list[str] = Field(default_factory=list, description="Directive rules/observations that were applied")
 
 
 class TokenUsage(BaseModel):
@@ -169,28 +166,6 @@ class ChunkInfo(BaseModel):
     truncated: bool = Field(default=False, description="Whether the chunk was truncated due to token limits")
 
 
-class ObservationResult(BaseModel):
-    """An observation result from recall (consolidated knowledge synthesized from facts)."""
-
-    id: str = Field(description="Unique observation ID")
-    text: str = Field(description="The observation text")
-    proof_count: int = Field(description="Number of facts supporting this observation")
-    relevance: float = Field(default=0.0, description="Relevance score to the query")
-    tags: list[str] | None = Field(default=None, description="Tags for visibility scoping")
-    source_memory_ids: list[str] = Field(
-        default_factory=list, description="IDs of facts that contribute to this observation"
-    )
-
-
-class MentalModelResult(BaseModel):
-    """A mental model result from recall (stored reflect response)."""
-
-    id: str = Field(description="Unique mental model ID")
-    name: str = Field(description="Human-readable name")
-    content: str = Field(description="The synthesized content")
-    relevance: float = Field(default=0.0, description="Relevance score to the query")
-
-
 class RecallResult(BaseModel):
     """
     Result from a recall operation.
@@ -254,14 +229,6 @@ class ReflectResult(BaseModel):
                     ],
                     "experience": [],
                     "opinion": [],
-                    "mental_models": [],
-                    "directives": [
-                        {
-                            "id": "directive-123",
-                            "name": "Response Style",
-                            "rules": ["Always be concise"],
-                        }
-                    ],
                 },
                 "new_opinions": ["Machine learning has great potential in healthcare"],
                 "structured_output": {"summary": "ML in healthcare", "confidence": 0.9},
@@ -271,8 +238,8 @@ class ReflectResult(BaseModel):
     )
 
     text: str = Field(description="The formulated answer text")
-    based_on: dict[str, Any] = Field(
-        description="Facts used to formulate the answer, organized by type (world, experience, opinion, mental_models, directives)"
+    based_on: dict[str, list[MemoryFact]] = Field(
+        description="Facts used to formulate the answer, organized by type (world, experience, opinion)"
     )
     new_opinions: list[str] = Field(default_factory=list, description="List of newly formed opinions during reflection")
     structured_output: dict[str, Any] | None = Field(
@@ -291,6 +258,10 @@ class ReflectResult(BaseModel):
         default_factory=list,
         description="Trace of LLM calls made during reflection. Only present when include.tool_calls is enabled.",
     )
+    mental_models: list[MentalModelRef] = Field(
+        default_factory=list,
+        description="Mental models accessed during reflection, including directives (subtype='directive').",
+    )
     directives_applied: list[DirectiveRef] = Field(
         default_factory=list,
         description="Directive mental models that were applied during this reflection.",

hindsight-api/hindsight_api/engine/retain/fact_extraction.py

@@ -114,8 +114,11 @@ class CausalRelation(BaseModel):
     """Causal relationship from this fact to a previous fact (stored format)."""
 
     target_fact_index: int = Field(description="Index of the related fact in the facts array (0-based).")
-    relation_type: Literal["caused_by"] = Field(
-        description="How this fact relates to the target: 'caused_by' = this fact was caused by the target"
+    relation_type: Literal["caused_by", "enabled_by", "prevented_by"] = Field(
+        description="How this fact relates to the target: "
+        "'caused_by' = this fact was caused by the target, "
+        "'enabled_by' = this fact was enabled by the target, "
+        "'prevented_by' = this fact was prevented by the target"
     )
     strength: float = Field(
         description="Strength of relationship (0.0 to 1.0)",
@@ -138,8 +141,11 @@ class FactCausalRelation(BaseModel):
         "MUST be less than this fact's position in the list. "
         "Example: if this is fact #5, target_index can only be 0, 1, 2, 3, or 4."
     )
-    relation_type: Literal["caused_by"] = Field(
-        description="How this fact relates to the target fact: 'caused_by' = this fact was caused by the target fact"
+    relation_type: Literal["caused_by", "enabled_by", "prevented_by"] = Field(
+        description="How this fact relates to the target fact: "
+        "'caused_by' = this fact was caused by the target fact, "
+        "'enabled_by' = this fact was enabled by the target fact, "
+        "'prevented_by' = this fact was blocked/prevented by the target fact"
     )
     strength: float = Field(
         description="Strength of relationship (0.0 to 1.0). 1.0 = strong, 0.5 = moderate",
@@ -432,15 +438,34 @@ def _chunk_conversation(turns: list[dict], max_chars: int) -> list[str]:
 # FACT EXTRACTION PROMPTS
 # =============================================================================
 
-# Base prompt template (shared by concise and custom modes)
-# Uses {extraction_guidelines} placeholder for mode-specific instructions
-_BASE_FACT_EXTRACTION_PROMPT = """Extract SIGNIFICANT facts from text. Be SELECTIVE - only extract facts worth remembering long-term.
+# Concise extraction prompt (default) - selective, high-quality facts
+CONCISE_FACT_EXTRACTION_PROMPT = """Extract SIGNIFICANT facts from text. Be SELECTIVE - only extract facts worth remembering long-term.
 
-LANGUAGE REQUIREMENT: Detect the language of the input text. All extracted facts, entity names, descriptions, and other output MUST be in the SAME language as the input. Do not translate to another language.
+LANGUAGE RULE (CRITICAL): Output facts in the EXACT SAME language as the input text. If input is Japanese, output Japanese. If input is Chinese, output Chinese. NEVER translate to English. Preserve original language completely.
 
 {fact_types_instruction}
 
-{extraction_guidelines}
+══════════════════════════════════════════════════════════════════════════
+SELECTIVITY - CRITICAL (Reduces 90% of unnecessary output)
+══════════════════════════════════════════════════════════════════════════
+
+ONLY extract facts that are:
+✅ Personal info: names, relationships, roles, background
+✅ Preferences: likes, dislikes, habits, interests (e.g., "Alice likes coffee")
+✅ Significant events: milestones, decisions, achievements, changes
+✅ Plans/goals: future intentions, deadlines, commitments
+✅ Expertise: skills, knowledge, certifications, experience
+✅ Important context: projects, problems, constraints
+✅ Sensory/emotional details: feelings, sensations, perceptions that provide context
+✅ Observations: descriptions of people, places, things with specific details
+
+DO NOT extract:
+❌ Generic greetings: "how are you", "hello", pleasantries without substance
+❌ Pure filler: "thanks", "sounds good", "ok", "got it", "sure"
+❌ Process chatter: "let me check", "one moment", "I'll look into it"
+❌ Repeated info: if already stated, don't extract again
+
+CONSOLIDATE related statements into ONE fact when possible.
 
 ══════════════════════════════════════════════════════════════════════════
 FACT FORMAT - BE CONCISE
@@ -488,33 +513,7 @@ ENTITIES
 ══════════════════════════════════════════════════════════════════════════
 
 Include: people names, organizations, places, key objects, abstract concepts (career, friendship, etc.)
-Always include "user" when fact is about the user.{examples}"""
-
-# Concise mode guidelines
-_CONCISE_GUIDELINES = """══════════════════════════════════════════════════════════════════════════
-SELECTIVITY - CRITICAL (Reduces 90% of unnecessary output)
-══════════════════════════════════════════════════════════════════════════
-
-ONLY extract facts that are:
-✅ Personal info: names, relationships, roles, background
-✅ Preferences: likes, dislikes, habits, interests (e.g., "Alice likes coffee")
-✅ Significant events: milestones, decisions, achievements, changes
-✅ Plans/goals: future intentions, deadlines, commitments
-✅ Expertise: skills, knowledge, certifications, experience
-✅ Important context: projects, problems, constraints
-✅ Sensory/emotional details: feelings, sensations, perceptions that provide context
-✅ Observations: descriptions of people, places, things with specific details
-
-DO NOT extract:
-❌ Generic greetings: "how are you", "hello", pleasantries without substance
-❌ Pure filler: "thanks", "sounds good", "ok", "got it", "sure"
-❌ Process chatter: "let me check", "one moment", "I'll look into it"
-❌ Repeated info: if already stated, don't extract again
-
-CONSOLIDATE related statements into ONE fact when possible."""
-
-# Concise mode examples
-_CONCISE_EXAMPLES = """
+Always include "user" when fact is about the user.
 
 ══════════════════════════════════════════════════════════════════════════
 EXAMPLES
@@ -540,20 +539,6 @@ QUALITY OVER QUANTITY
 
 Ask: "Would this be useful to recall in 6 months?" If no, skip it."""
 
-# Assembled concise prompt (backward compatible - exact same output as before)
-CONCISE_FACT_EXTRACTION_PROMPT = _BASE_FACT_EXTRACTION_PROMPT.format(
-    fact_types_instruction="{fact_types_instruction}",
-    extraction_guidelines=_CONCISE_GUIDELINES,
-    examples=_CONCISE_EXAMPLES,
-)
-
-# Custom prompt uses same base but without examples
-CUSTOM_FACT_EXTRACTION_PROMPT = _BASE_FACT_EXTRACTION_PROMPT.format(
-    fact_types_instruction="{fact_types_instruction}",
-    extraction_guidelines="{custom_instructions}",
-    examples="",  # No examples for custom mode
-)
-
 
 # Verbose extraction prompt - detailed, comprehensive facts (legacy mode)
 VERBOSE_FACT_EXTRACTION_PROMPT = """Extract facts from text into structured format with FIVE required dimensions - BE EXTREMELY DETAILED.
@@ -677,7 +662,7 @@ CAUSAL RELATIONSHIPS
 ══════════════════════════════════════════════════════════════════════════
 
 Link facts with causal_relations (max 2 per fact). target_index must be < this fact's index.
-Type: "caused_by" (this fact was caused by the target fact)
+Types: "caused_by", "enabled_by", "prevented_by"
 
 Example: "Lost job → couldn't pay rent → moved apartment"
 - Fact 0: Lost job, causal_relations: null
@@ -701,12 +686,6 @@ async def _extract_facts_from_chunk(
     Note: event_date parameter is kept for backward compatibility but not used in prompt.
     The LLM extracts temporal information from the context string instead.
     """
-    import logging
-
-    from openai import BadRequestError
-
-    logger = logging.getLogger(__name__)
-
     memory_bank_context = f"\n- Your name: {agent_name}" if agent_name and extract_opinions else ""
 
     # Determine which fact types to extract based on the flag
@@ -725,27 +704,13 @@ async def _extract_facts_from_chunk(
     extract_causal_links = config.retain_extract_causal_links
 
     # Select base prompt based on extraction mode
-    if extraction_mode == "custom":
-        # Custom mode: inject user-provided guidelines
-        if not config.retain_custom_instructions:
-            logger.warning(
-                "extraction_mode='custom' but HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS not set. "
-                "Falling back to 'concise' mode."
-            )
-            base_prompt = CONCISE_FACT_EXTRACTION_PROMPT
-            prompt = base_prompt.format(fact_types_instruction=fact_types_instruction)
-        else:
-            base_prompt = CUSTOM_FACT_EXTRACTION_PROMPT
-            prompt = base_prompt.format(
-                fact_types_instruction=fact_types_instruction,
-                custom_instructions=config.retain_custom_instructions,
-            )
-    elif extraction_mode == "verbose":
+    if extraction_mode == "verbose":
         base_prompt = VERBOSE_FACT_EXTRACTION_PROMPT
-        prompt = base_prompt.format(fact_types_instruction=fact_types_instruction)
     else:
         base_prompt = CONCISE_FACT_EXTRACTION_PROMPT
-        prompt = base_prompt.format(fact_types_instruction=fact_types_instruction)
+
+    # Format the prompt with fact types instruction
+    prompt = base_prompt.format(fact_types_instruction=fact_types_instruction)
 
     # Build the full prompt with or without causal relationships section
     # Select appropriate response schema based on extraction mode and causal links
@@ -758,6 +723,12 @@ async def _extract_facts_from_chunk(
     else:
         response_schema = FactExtractionResponseNoCausal
 
+    import logging
+
+    from openai import BadRequestError
+
+    logger = logging.getLogger(__name__)
+
     # Retry logic for JSON validation errors
     max_retries = 2
     last_error = None
@@ -852,8 +823,7 @@ Text:
 
                 # Critical field: fact_type
                 # LLM uses "assistant" but we convert to "experience" for storage
-                original_fact_type = llm_fact.get("fact_type")
-                fact_type = original_fact_type
+                fact_type = llm_fact.get("fact_type")
 
                 # Convert "assistant" → "experience" for storage
                 if fact_type == "assistant":
@@ -870,10 +840,7 @@ Text:
                     else:
                         # Default to 'world' if we can't determine
                         fact_type = "world"
-                        logger.warning(
-                            f"Fact {i}: defaulting to fact_type='world' "
-                            f"(original fact_type={original_fact_type!r}, fact_kind={fact_kind!r})"
-                        )
+                        logger.warning(f"Fact {i}: defaulting to fact_type='world'")
 
                 # Get fact_kind for temporal handling (but don't store it)
                 fact_kind = llm_fact.get("fact_kind", "conversation")

hindsight-api/hindsight_api/engine/retain/link_utils.py

@@ -754,14 +754,17 @@ async def create_causal_links_batch(
         causal_relations_per_fact: List of causal relations for each fact.
             Each element is a list of dicts with:
             - target_fact_index: Index into unit_ids for the target fact
-            - relation_type: "caused_by"
+            - relation_type: "causes", "caused_by", "enables", or "prevents"
             - strength: Float in [0.0, 1.0] representing relationship strength
 
     Returns:
         Number of causal links created
 
-    Causal link type:
-    - "caused_by": This fact was caused by the target fact
+    Causal link types:
+    - "causes": This fact directly causes the target fact (forward causation)
+    - "caused_by": This fact was caused by the target fact (backward causation)
+    - "enables": This fact enables/allows the target fact (enablement)
+    - "prevents": This fact prevents/blocks the target fact (prevention)
     """
     if not unit_ids or not causal_relations_per_fact:
         return 0
@@ -784,8 +787,8 @@ async def create_causal_links_batch(
                 relation_type = relation["relation_type"]
                 strength = relation.get("strength", 1.0)
 
-                # Validate relation_type - only "caused_by" is supported (DB constraint)
-                valid_types = {"caused_by"}
+                # Validate relation_type - must match database constraint
+                valid_types = {"causes", "caused_by", "enables", "prevents"}
                 if relation_type not in valid_types:
                     logger.error(
                         f"Invalid relation_type '{relation_type}' (type: {type(relation_type).__name__}) "

hindsight-api/hindsight_api/engine/retain/types.py

@@ -86,10 +86,10 @@ class CausalRelation:
     """
     Causal relationship between facts.
 
-    Represents how one fact was caused by another.
+    Represents how one fact causes, enables, or prevents another.
     """
 
-    relation_type: str  # "caused_by"
+    relation_type: str  # "causes", "enables", "prevents", "caused_by"
     target_fact_index: int  # Index of the target fact in the batch
     strength: float = 1.0  # Strength of the causal relationship
 

hindsight-api/hindsight_api/engine/search/link_expansion_retrieval.py

@@ -155,6 +155,7 @@ class LinkExpansionRetriever(GraphRetriever):
                 all_seeds.extend(temporal_seeds)
 
             if not all_seeds:
+                logger.debug("[LinkExpansion] No seeds found, returning empty results")
                 return [], timings
 
             seed_ids = list({s.id for s in all_seeds})
@@ -163,102 +164,30 @@ class LinkExpansionRetriever(GraphRetriever):
             # Run entity and causal expansion sequentially on same connection
             query_start = time.time()
 
-            # For observations, traverse through source_memory_ids to find entity connections.
-            # Observations don't have direct unit_entities - they inherit entities via their
-            # source world/experience facts.
-            #
-            # Path: observation → source_memory_ids → world fact → entities →
-            #       ALL world facts with those entities → their observations (excluding seeds)
-            if fact_type == "observation":
-                # Debug: Check what source_memory_ids exist on seed observations
-                debug_sources = await conn.fetch(
-                    f"""
-                    SELECT id, source_memory_ids
-                    FROM {fq_table("memory_units")}
-                    WHERE id = ANY($1::uuid[])
-                    """,
-                    seed_ids,
-                )
-                source_ids_found = []
-                for row in debug_sources:
-                    if row["source_memory_ids"]:
-                        source_ids_found.extend(row["source_memory_ids"])
-                logger.debug(
-                    f"[LinkExpansion] observation graph: {len(seed_ids)} seeds, "
-                    f"{len(source_ids_found)} source_memory_ids found"
-                )
-
-                entity_rows = await conn.fetch(
-                    f"""
-                    WITH seed_sources AS (
-                        -- Get source memory IDs from seed observations
-                        SELECT DISTINCT unnest(source_memory_ids) AS source_id
-                        FROM {fq_table("memory_units")}
-                        WHERE id = ANY($1::uuid[])
-                          AND source_memory_ids IS NOT NULL
-                    ),
-                    source_entities AS (
-                        -- Get entities from those source memories (filtered by frequency)
-                        SELECT DISTINCT ue.entity_id
-                        FROM seed_sources ss
-                        JOIN {fq_table("unit_entities")} ue ON ss.source_id = ue.unit_id
-                        JOIN {fq_table("entities")} e ON ue.entity_id = e.id
-                        WHERE e.mention_count < $2
-                    ),
-                    all_connected_sources AS (
-                        -- Find ALL world facts sharing those entities (don't exclude seed sources)
-                        -- The exclusion happens at the observation level, not the source level
-                        SELECT DISTINCT other_ue.unit_id AS source_id
-                        FROM source_entities se
-                        JOIN {fq_table("unit_entities")} other_ue ON se.entity_id = other_ue.entity_id
-                    )
-                    -- Find observations derived from connected source memories
-                    -- Only exclude the actual seed observations
-                    SELECT
-                        mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                        mu.occurred_end, mu.mentioned_at, mu.embedding,
-                        mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                        COUNT(DISTINCT cs.source_id)::float AS score
-                    FROM all_connected_sources cs
-                    JOIN {fq_table("memory_units")} mu
-                        ON mu.source_memory_ids @> ARRAY[cs.source_id]
-                    WHERE mu.fact_type = 'observation'
-                      AND mu.id != ALL($1::uuid[])
-                    GROUP BY mu.id
-                    ORDER BY score DESC
-                    LIMIT $3
-                    """,
-                    seed_ids,
-                    self.max_entity_frequency,
-                    budget,
-                )
-                logger.debug(f"[LinkExpansion] observation graph: found {len(entity_rows)} connected observations")
-            else:
-                # For world/experience facts, use direct entity lookup
-                entity_rows = await conn.fetch(
-                    f"""
-                    SELECT
-                        mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                        mu.occurred_end, mu.mentioned_at, mu.embedding,
-                        mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                        COUNT(*)::float AS score
-                    FROM {fq_table("unit_entities")} seed_ue
-                    JOIN {fq_table("entities")} e ON seed_ue.entity_id = e.id
-                    JOIN {fq_table("unit_entities")} other_ue ON seed_ue.entity_id = other_ue.entity_id
-                    JOIN {fq_table("memory_units")} mu ON other_ue.unit_id = mu.id
-                    WHERE seed_ue.unit_id = ANY($1::uuid[])
-                      AND e.mention_count < $2
-                      AND mu.id != ALL($1::uuid[])
-                      AND mu.fact_type = $3
-                    GROUP BY mu.id
-                    ORDER BY score DESC
-                    LIMIT $4
-                    """,
-                    seed_ids,
-                    self.max_entity_frequency,
-                    fact_type,
-                    budget,
-                )
+            entity_rows = await conn.fetch(
+                f"""
+                SELECT
+                    mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
+                    mu.occurred_end, mu.mentioned_at, mu.embedding,
+                    mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
+                    COUNT(*)::float AS score
+                FROM {fq_table("unit_entities")} seed_ue
+                JOIN {fq_table("entities")} e ON seed_ue.entity_id = e.id
+                JOIN {fq_table("unit_entities")} other_ue ON seed_ue.entity_id = other_ue.entity_id
+                JOIN {fq_table("memory_units")} mu ON other_ue.unit_id = mu.id
+                WHERE seed_ue.unit_id = ANY($1::uuid[])
+                  AND e.mention_count < $2
+                  AND mu.id != ALL($1::uuid[])
+                  AND mu.fact_type = $3
+                GROUP BY mu.id
+                ORDER BY score DESC
+                LIMIT $4
+                """,
+                seed_ids,
+                self.max_entity_frequency,
+                fact_type,
+                budget,
+            )
 
             causal_rows = await conn.fetch(
                 f"""
@@ -282,69 +211,11 @@ class LinkExpansionRetriever(GraphRetriever):
                 budget,
             )
 
-            # Fallback: semantic/temporal/entity links from memory_links table
-            # These are secondary to entity links (via unit_entities) and causal links
-            # Weight is halved (0.5x) to prioritize primary link types
-            # Check both directions: seeds -> others AND others -> seeds
-            fallback_rows = await conn.fetch(
-                f"""
-                WITH outgoing AS (
-                    -- Links FROM seeds TO other facts
-                    SELECT mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                           mu.occurred_end, mu.mentioned_at, mu.embedding,
-                           mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                           ml.weight
-                    FROM {fq_table("memory_links")} ml
-                    JOIN {fq_table("memory_units")} mu ON ml.to_unit_id = mu.id
-                    WHERE ml.from_unit_id = ANY($1::uuid[])
-                      AND ml.link_type IN ('semantic', 'temporal', 'entity')
-                      AND ml.weight >= $2
-                      AND mu.fact_type = $3
-                      AND mu.id != ALL($1::uuid[])
-                ),
-                incoming AS (
-                    -- Links FROM other facts TO seeds (reverse direction)
-                    SELECT mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                           mu.occurred_end, mu.mentioned_at, mu.embedding,
-                           mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                           ml.weight
-                    FROM {fq_table("memory_links")} ml
-                    JOIN {fq_table("memory_units")} mu ON ml.from_unit_id = mu.id
-                    WHERE ml.to_unit_id = ANY($1::uuid[])
-                      AND ml.link_type IN ('semantic', 'temporal', 'entity')
-                      AND ml.weight >= $2
-                      AND mu.fact_type = $3
-                      AND mu.id != ALL($1::uuid[])
-                ),
-                combined AS (
-                    SELECT * FROM outgoing
-                    UNION ALL
-                    SELECT * FROM incoming
-                )
-                SELECT DISTINCT ON (id)
-                    id, text, context, event_date, occurred_start,
-                    occurred_end, mentioned_at, embedding,
-                    fact_type, document_id, chunk_id, tags,
-                    (MAX(weight) * 0.5) AS score
-                FROM combined
-                GROUP BY id, text, context, event_date, occurred_start,
-                         occurred_end, mentioned_at, embedding,
-                         fact_type, document_id, chunk_id, tags
-                ORDER BY id, score DESC
-                LIMIT $4
-                """,
-                seed_ids,
-                self.causal_weight_threshold,
-                fact_type,
-                budget,
-            )
-
             timings.edge_load_time = time.time() - query_start
-            timings.db_queries = 3
-            timings.edge_count = len(entity_rows) + len(causal_rows) + len(fallback_rows)
+            timings.db_queries = 2
+            timings.edge_count = len(entity_rows) + len(causal_rows)
 
         # Merge results, taking max score per fact
-        # Priority: entity links (unit_entities) > causal links > fallback links
         score_map: dict[str, float] = {}
         row_map: dict[str, dict] = {}
 
@@ -359,12 +230,6 @@ class LinkExpansionRetriever(GraphRetriever):
             if fact_id not in row_map:
                 row_map[fact_id] = dict(row)
 
-        for row in fallback_rows:
-            fact_id = str(row["id"])
-            score_map[fact_id] = max(score_map.get(fact_id, 0), row["score"])
-            if fact_id not in row_map:
-                row_map[fact_id] = dict(row)
-
         # Sort by score and limit
         sorted_ids = sorted(score_map.keys(), key=lambda x: score_map[x], reverse=True)[:budget]
         rows = [row_map[fact_id] for fact_id in sorted_ids]

hindsight-api/hindsight_api/engine/search/scoring.py

@@ -0,0 +1,134 @@
+"""
+Scoring functions for memory search and retrieval.
+
+Includes recency weighting, frequency weighting, temporal proximity,
+and similarity calculations used in memory activation and ranking.
+"""
+
+from datetime import datetime
+
+
+def cosine_similarity(vec1: list[float], vec2: list[float]) -> float:
+    """
+    Calculate cosine similarity between two vectors.
+
+    Args:
+        vec1: First vector
+        vec2: Second vector
+
+    Returns:
+        Similarity score between 0 and 1
+    """
+    if len(vec1) != len(vec2):
+        raise ValueError("Vectors must have same dimension")
+
+    dot_product = sum(a * b for a, b in zip(vec1, vec2))
+    magnitude1 = sum(a * a for a in vec1) ** 0.5
+    magnitude2 = sum(b * b for b in vec2) ** 0.5
+
+    if magnitude1 == 0 or magnitude2 == 0:
+        return 0.0
+
+    return dot_product / (magnitude1 * magnitude2)
+
+
+def calculate_recency_weight(days_since: float, half_life_days: float = 365.0) -> float:
+    """
+    Calculate recency weight using logarithmic decay.
+
+    This provides much better differentiation over long time periods compared to
+    exponential decay. Uses a log-based decay where the half-life parameter controls
+    when memories reach 50% weight.
+
+    Examples:
+        - Today (0 days): 1.0
+        - 1 year (365 days): ~0.5 (with default half_life=365)
+        - 2 years (730 days): ~0.33
+        - 5 years (1825 days): ~0.17
+        - 10 years (3650 days): ~0.09
+
+    This ensures that 2-year-old and 5-year-old memories have meaningfully
+    different weights, unlike exponential decay which makes them both ~0.
+
+    Args:
+        days_since: Number of days since the memory was created
+        half_life_days: Number of days for weight to reach 0.5 (default: 1 year)
+
+    Returns:
+        Weight between 0 and 1
+    """
+    import math
+
+    # Logarithmic decay: 1 / (1 + log(1 + days_since/half_life))
+    # This decays much slower than exponential, giving better long-term differentiation
+    normalized_age = days_since / half_life_days
+    return 1.0 / (1.0 + math.log1p(normalized_age))
+
+
+def calculate_temporal_anchor(occurred_start: datetime, occurred_end: datetime) -> datetime:
+    """
+    Calculate a single temporal anchor point from a temporal range.
+
+    Used for spreading activation - we need a single representative date
+    to calculate temporal proximity between facts. This simplifies the
+    range-to-range distance problem.
+
+    Strategy: Use midpoint of the range for balanced representation.
+
+    Args:
+        occurred_start: Start of temporal range
+        occurred_end: End of temporal range
+
+    Returns:
+        Single datetime representing the temporal anchor (midpoint)
+
+    Examples:
+        - Point event (July 14): start=July 14, end=July 14 → anchor=July 14
+        - Month range (February): start=Feb 1, end=Feb 28 → anchor=Feb 14
+        - Year range (2023): start=Jan 1, end=Dec 31 → anchor=July 1
+    """
+    # Calculate midpoint
+    time_delta = occurred_end - occurred_start
+    midpoint = occurred_start + (time_delta / 2)
+    return midpoint
+
+
+def calculate_temporal_proximity(anchor_a: datetime, anchor_b: datetime, half_life_days: float = 30.0) -> float:
+    """
+    Calculate temporal proximity between two temporal anchors.
+
+    Used for spreading activation to determine how "close" two facts are
+    in time. Uses logarithmic decay so that temporal similarity doesn't
+    drop off too quickly.
+
+    Args:
+        anchor_a: Temporal anchor of first fact
+        anchor_b: Temporal anchor of second fact
+        half_life_days: Number of days for proximity to reach 0.5
+                       (default: 30 days = 1 month)
+
+    Returns:
+        Proximity score in [0, 1] where:
+        - 1.0 = same day
+        - 0.5 = ~half_life days apart
+        - 0.0 = very distant in time
+
+    Examples:
+        - Same day: 1.0
+        - 1 week apart (half_life=30): ~0.7
+        - 1 month apart (half_life=30): ~0.5
+        - 1 year apart (half_life=30): ~0.2
+    """
+    import math
+
+    days_apart = abs((anchor_a - anchor_b).days)
+
+    if days_apart == 0:
+        return 1.0
+
+    # Logarithmic decay: 1 / (1 + log(1 + days_apart/half_life))
+    # Similar to calculate_recency_weight but for proximity between events
+    normalized_distance = days_apart / half_life_days
+    proximity = 1.0 / (1.0 + math.log1p(normalized_distance))
+
+    return proximity

hindsight-api/hindsight_api/engine/search/tracer.py

@@ -330,8 +330,8 @@ class SearchTracer:
                 RetrievalResult(
                     rank=rank,
                     node_id=doc_id,
-                    text=data.get("text") or "",
-                    context=data.get("context") or "",
+                    text=data.get("text", ""),
+                    context=data.get("context", ""),
                     event_date=data.get("event_date"),
                     fact_type=data.get("fact_type") or fact_type,
                     score=score,

hindsight-api/hindsight_api/engine/task_backend.py

@@ -144,21 +144,17 @@ class BrokerTaskBackend(TaskBackend):
         self,
         pool_getter: Callable[[], "asyncpg.Pool"],
         schema: str | None = None,
-        schema_getter: Callable[[], str | None] | None = None,
     ):
         """
         Initialize the broker task backend.
 
         Args:
             pool_getter: Callable that returns the asyncpg connection pool
-            schema: Database schema for multi-tenant support (optional, static)
-            schema_getter: Callable that returns current schema dynamically (optional).
-                          If set, takes precedence over static schema for submit_task.
+            schema: Database schema for multi-tenant support (optional)
         """
         super().__init__()
         self._pool_getter = pool_getter
         self._schema = schema
-        self._schema_getter = schema_getter
 
     async def initialize(self):
         """Initialize the backend."""
@@ -184,8 +180,7 @@ class BrokerTaskBackend(TaskBackend):
         bank_id = task_dict.get("bank_id")
         payload_json = json.dumps(task_dict)
 
-        schema = self._schema_getter() if self._schema_getter else self._schema
-        table = fq_table("async_operations", schema)
+        table = fq_table("async_operations", self._schema)
 
         if operation_id:
             # Update existing operation with task payload
@@ -236,8 +231,7 @@ class BrokerTaskBackend(TaskBackend):
         import asyncio
 
         pool = self._pool_getter()
-        schema = self._schema_getter() if self._schema_getter else self._schema
-        table = fq_table("async_operations", schema)
+        table = fq_table("async_operations", self._schema)
 
         start_time = asyncio.get_event_loop().time()
         while asyncio.get_event_loop().time() - start_time < timeout:

hindsight-api/hindsight_api/engine/utils.py

@@ -65,3 +65,129 @@ async def extract_facts(
         return [], chunks
 
     return facts, chunks
+
+
+def cosine_similarity(vec1: list[float], vec2: list[float]) -> float:
+    """
+    Calculate cosine similarity between two vectors.
+
+    Args:
+        vec1: First vector
+        vec2: Second vector
+
+    Returns:
+        Similarity score between 0 and 1
+    """
+    if len(vec1) != len(vec2):
+        raise ValueError("Vectors must have same dimension")
+
+    dot_product = sum(a * b for a, b in zip(vec1, vec2))
+    magnitude1 = sum(a * a for a in vec1) ** 0.5
+    magnitude2 = sum(b * b for b in vec2) ** 0.5
+
+    if magnitude1 == 0 or magnitude2 == 0:
+        return 0.0
+
+    return dot_product / (magnitude1 * magnitude2)
+
+
+def calculate_recency_weight(days_since: float, half_life_days: float = 365.0) -> float:
+    """
+    Calculate recency weight using logarithmic decay.
+
+    This provides much better differentiation over long time periods compared to
+    exponential decay. Uses a log-based decay where the half-life parameter controls
+    when memories reach 50% weight.
+
+    Examples:
+        - Today (0 days): 1.0
+        - 1 year (365 days): ~0.5 (with default half_life=365)
+        - 2 years (730 days): ~0.33
+        - 5 years (1825 days): ~0.17
+        - 10 years (3650 days): ~0.09
+
+    This ensures that 2-year-old and 5-year-old memories have meaningfully
+    different weights, unlike exponential decay which makes them both ~0.
+
+    Args:
+        days_since: Number of days since the memory was created
+        half_life_days: Number of days for weight to reach 0.5 (default: 1 year)
+
+    Returns:
+        Weight between 0 and 1
+    """
+    import math
+
+    # Logarithmic decay: 1 / (1 + log(1 + days_since/half_life))
+    # This decays much slower than exponential, giving better long-term differentiation
+    normalized_age = days_since / half_life_days
+    return 1.0 / (1.0 + math.log1p(normalized_age))
+
+
+def calculate_temporal_anchor(occurred_start: datetime, occurred_end: datetime) -> datetime:
+    """
+    Calculate a single temporal anchor point from a temporal range.
+
+    Used for spreading activation - we need a single representative date
+    to calculate temporal proximity between facts. This simplifies the
+    range-to-range distance problem.
+
+    Strategy: Use midpoint of the range for balanced representation.
+
+    Args:
+        occurred_start: Start of temporal range
+        occurred_end: End of temporal range
+
+    Returns:
+        Single datetime representing the temporal anchor (midpoint)
+
+    Examples:
+        - Point event (July 14): start=July 14, end=July 14 → anchor=July 14
+        - Month range (February): start=Feb 1, end=Feb 28 → anchor=Feb 14
+        - Year range (2023): start=Jan 1, end=Dec 31 → anchor=July 1
+    """
+    # Calculate midpoint
+    time_delta = occurred_end - occurred_start
+    midpoint = occurred_start + (time_delta / 2)
+    return midpoint
+
+
+def calculate_temporal_proximity(anchor_a: datetime, anchor_b: datetime, half_life_days: float = 30.0) -> float:
+    """
+    Calculate temporal proximity between two temporal anchors.
+
+    Used for spreading activation to determine how "close" two facts are
+    in time. Uses logarithmic decay so that temporal similarity doesn't
+    drop off too quickly.
+
+    Args:
+        anchor_a: Temporal anchor of first fact
+        anchor_b: Temporal anchor of second fact
+        half_life_days: Number of days for proximity to reach 0.5
+                       (default: 30 days = 1 month)
+
+    Returns:
+        Proximity score in [0, 1] where:
+        - 1.0 = same day
+        - 0.5 = ~half_life days apart
+        - 0.0 = very distant in time
+
+    Examples:
+        - Same day: 1.0
+        - 1 week apart (half_life=30): ~0.7
+        - 1 month apart (half_life=30): ~0.5
+        - 1 year apart (half_life=30): ~0.2
+    """
+    import math
+
+    days_apart = abs((anchor_a - anchor_b).days)
+
+    if days_apart == 0:
+        return 1.0
+
+    # Logarithmic decay: 1 / (1 + log(1 + days_apart/half_life))
+    # Similar to calculate_recency_weight but for proximity between events
+    normalized_distance = days_apart / half_life_days
+    proximity = 1.0 / (1.0 + math.log1p(normalized_distance))
+
+    return proximity

hindsight-api/hindsight_api/extensions/__init__.py

@@ -21,23 +21,20 @@ from hindsight_api.extensions.context import DefaultExtensionContext, ExtensionC
 from hindsight_api.extensions.http import HttpExtension
 from hindsight_api.extensions.loader import load_extension
 from hindsight_api.extensions.operation_validator import (
-    # Consolidation operation
-    ConsolidateContext,
-    ConsolidateResult,
-    # Core operations
     OperationValidationError,
     OperationValidatorExtension,
     RecallContext,
     RecallResult,
     ReflectContext,
     ReflectResultContext,
+    RefreshMentalModelContext,
+    RefreshMentalModelResult,
     RetainContext,
     RetainResult,
     ValidationResult,
 )
 from hindsight_api.extensions.tenant import (
     AuthenticationError,
-    Tenant,
     TenantContext,
     TenantExtension,
 )
@@ -52,24 +49,22 @@ __all__ = [
     "DefaultExtensionContext",
     # HTTP Extension
     "HttpExtension",
-    # Operation Validator - Core
+    # Operation Validator
     "OperationValidationError",
     "OperationValidatorExtension",
     "RecallContext",
     "RecallResult",
     "ReflectContext",
     "ReflectResultContext",
+    "RefreshMentalModelContext",
+    "RefreshMentalModelResult",
     "RetainContext",
     "RetainResult",
     "ValidationResult",
-    # Operation Validator - Consolidation
-    "ConsolidateContext",
-    "ConsolidateResult",
     # Tenant/Auth
     "ApiKeyTenantExtension",
     "AuthenticationError",
     "RequestContext",
-    "Tenant",
     "TenantContext",
     "TenantExtension",
 ]

hindsight-api/hindsight_api/extensions/builtin/tenant.py

@@ -1,6 +1,6 @@
 """Built-in tenant extension implementations."""
 
-from hindsight_api.extensions.tenant import AuthenticationError, Tenant, TenantContext, TenantExtension
+from hindsight_api.extensions.tenant import AuthenticationError, TenantContext, TenantExtension
 from hindsight_api.models import RequestContext
 
 
@@ -31,7 +31,3 @@ class ApiKeyTenantExtension(TenantExtension):
         if context.api_key != self.expected_api_key:
             raise AuthenticationError("Invalid API key")
         return TenantContext(schema_name="public")
-
-    async def list_tenants(self) -> list[Tenant]:
-        """Return public schema for single-tenant setup."""
-        return [Tenant(schema="public")]

hindsight-api/hindsight_api/extensions/operation_validator.py

@@ -1,4 +1,4 @@
-"""Operation Validator Extension for validating retain/recall/reflect/consolidate operations."""
+"""Operation Validator Extension for validating retain/recall/reflect operations."""
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
@@ -97,16 +97,15 @@ class ReflectContext:
     context: str | None = None
 
 
-# =============================================================================
-# Consolidation Pre-operation Context
-# =============================================================================
-
-
 @dataclass
-class ConsolidateContext:
-    """Context for a consolidation operation validation (pre-operation)."""
+class RefreshMentalModelContext:
+    """Context for a refresh mental model operation validation (pre-operation).
+
+    Contains ALL user-provided parameters for the refresh mental model operation.
+    """
 
     bank_id: str
+    model_id: str
     request_context: "RequestContext"
 
 
@@ -177,28 +176,30 @@ class ReflectResultContext:
     error: str | None = None
 
 
-# =============================================================================
-# Consolidation Post-operation Context
-# =============================================================================
-
-
 @dataclass
-class ConsolidateResult:
-    """Result context for post-consolidation hook."""
+class RefreshMentalModelResult:
+    """Result context for post-refresh-mental-model hook.
+
+    Contains the operation parameters and the result including token usage.
+    """
 
     bank_id: str
+    model_id: str
     request_context: "RequestContext"
     # Result
-    processed: int = 0
-    created: int = 0
-    updated: int = 0
+    model_name: str | None = None
+    observations_count: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    duration_ms: int = 0
     success: bool = True
     error: str | None = None
 
 
 class OperationValidatorExtension(Extension, ABC):
     """
-    Validates and hooks into retain/recall/reflect/consolidate operations.
+    Validates and hooks into retain/recall/reflect operations.
 
     This extension allows implementing custom logic such as:
     - Rate limiting (pre-operation)
@@ -217,13 +218,9 @@ class OperationValidatorExtension(Extension, ABC):
         -> config = {"max_requests": "100"}
 
     Hook execution order:
-        1. validate_* (pre-operation)
+        1. validate_retain/validate_recall/validate_reflect (pre-operation)
         2. [operation executes]
-        3. on_*_complete (post-operation)
-
-    Supported operations:
-        - retain, recall, reflect (core memory operations)
-        - consolidate (mental models consolidation)
+        3. on_retain_complete/on_recall_complete/on_reflect_complete (post-operation)
     """
 
     # =========================================================================
@@ -301,6 +298,25 @@ class OperationValidatorExtension(Extension, ABC):
         """
         ...
 
+    @abstractmethod
+    async def validate_refresh_mental_model(self, ctx: RefreshMentalModelContext) -> ValidationResult:
+        """
+        Validate a refresh mental model operation before execution.
+
+        Called before the refresh mental model operation is processed.
+        Return ValidationResult.reject() to prevent the operation from executing.
+
+        Args:
+            ctx: Context containing all user-provided parameters:
+                - bank_id: Bank identifier
+                - model_id: Mental model ID to refresh
+                - request_context: Request context with auth info
+
+        Returns:
+            ValidationResult indicating whether the operation is allowed.
+        """
+        ...
+
     # =========================================================================
     # Post-operation hooks (optional - override to implement)
     # =========================================================================
@@ -362,42 +378,26 @@ class OperationValidatorExtension(Extension, ABC):
         """
         pass
 
-    # =========================================================================
-    # Consolidation - Pre-operation validation hook (optional - override to implement)
-    # =========================================================================
-
-    async def validate_consolidate(self, ctx: ConsolidateContext) -> ValidationResult:
+    async def on_refresh_mental_model_complete(self, result: RefreshMentalModelResult) -> None:
         """
-        Validate a consolidation operation before execution.
+        Called after a refresh mental model operation completes (success or failure).
 
-        Override to implement custom validation logic for consolidation.
-
-        Args:
-            ctx: Context containing:
-                - bank_id: Bank identifier
-                - request_context: Request context with auth info
-
-        Returns:
-            ValidationResult indicating whether the operation is allowed.
-        """
-        return ValidationResult.accept()
-
-    # =========================================================================
-    # Consolidation - Post-operation hook (optional - override to implement)
-    # =========================================================================
-
-    async def on_consolidate_complete(self, result: ConsolidateResult) -> None:
-        """
-        Called after a consolidation operation completes (success or failure).
-
-        Override to implement post-operation logic such as usage tracking or audit logging.
+        Override this method to implement post-operation logic such as:
+        - Token usage tracking and billing
+        - Audit logging
+        - Metrics collection
 
         Args:
             result: Result context containing:
                 - bank_id: Bank identifier
-                - processed: Number of memories processed
-                - created: Number of mental models created
-                - updated: Number of mental models updated
+                - model_id: Mental model ID
+                - request_context: Request context with auth info
+                - model_name: Name of the mental model (if success)
+                - observations_count: Number of observations generated
+                - input_tokens: Number of input tokens used
+                - output_tokens: Number of output tokens used
+                - total_tokens: Total tokens used (input + output)
+                - duration_ms: Total operation duration in milliseconds
                 - success: Whether the operation succeeded
                 - error: Error message (if failed)
         """

hindsight-api/hindsight_api/extensions/tenant.py

@@ -28,18 +28,6 @@ class TenantContext:
     schema_name: str
 
 
-@dataclass
-class Tenant:
-    """
-    Represents a tenant for worker discovery.
-
-    Used by list_tenants() to return tenant information including
-    the PostgreSQL schema name for database operations.
-    """
-
-    schema: str
-
-
 class TenantExtension(Extension, ABC):
     """
     Extension for multi-tenancy and API key authentication.
@@ -73,17 +61,3 @@ class TenantExtension(Extension, ABC):
             AuthenticationError: If authentication fails.
         """
         ...
-
-    @abstractmethod
-    async def list_tenants(self) -> list[Tenant]:
-        """
-        List all tenants that should be processed by workers.
-
-        This method is used by the worker to discover all tenants that need
-        task polling. Workers will poll for pending tasks in each tenant's schema.
-
-        Returns:
-            List of Tenant objects containing schema information.
-            For single-tenant setups, return [Tenant(schema="public")].
-        """
-        ...

hindsight-api/hindsight_api/main.py

@@ -184,10 +184,6 @@ def main():
             reflect_llm_api_key=config.reflect_llm_api_key,
             reflect_llm_model=config.reflect_llm_model,
             reflect_llm_base_url=config.reflect_llm_base_url,
-            consolidation_llm_provider=config.consolidation_llm_provider,
-            consolidation_llm_api_key=config.consolidation_llm_api_key,
-            consolidation_llm_model=config.consolidation_llm_model,
-            consolidation_llm_base_url=config.consolidation_llm_base_url,
             embeddings_provider=config.embeddings_provider,
             embeddings_local_model=config.embeddings_local_model,
             embeddings_tei_url=config.embeddings_tei_url,
@@ -209,14 +205,13 @@ def main():
             mpfp_top_k_neighbors=config.mpfp_top_k_neighbors,
             recall_max_concurrent=config.recall_max_concurrent,
             recall_connection_budget=config.recall_connection_budget,
+            observation_min_facts=config.observation_min_facts,
+            observation_top_entities=config.observation_top_entities,
             retain_max_completion_tokens=config.retain_max_completion_tokens,
             retain_chunk_size=config.retain_chunk_size,
             retain_extract_causal_links=config.retain_extract_causal_links,
             retain_extraction_mode=config.retain_extraction_mode,
-            retain_custom_instructions=config.retain_custom_instructions,
             retain_observations_async=config.retain_observations_async,
-            enable_observations=config.enable_observations,
-            consolidation_batch_size=config.consolidation_batch_size,
             skip_llm_verification=config.skip_llm_verification,
             lazy_reranker=config.lazy_reranker,
             run_migrations_on_startup=config.run_migrations_on_startup,

hindsight-api/hindsight_api/mcp_local.py

@@ -44,6 +44,7 @@ import os
 import sys
 
 from mcp.server.fastmcp import FastMCP
+from mcp.types import Icon
 
 from hindsight_api.config import (
     DEFAULT_MCP_LOCAL_BANK_ID,
@@ -52,7 +53,6 @@ from hindsight_api.config import (
     ENV_MCP_INSTRUCTIONS,
     ENV_MCP_LOCAL_BANK_ID,
 )
-from hindsight_api.mcp_tools import MCPToolsConfig, register_mcp_tools
 
 # Configure logging - default to warning to avoid polluting stderr during MCP init
 # MCP clients interpret stderr output as errors, so we suppress INFO logs by default
@@ -85,6 +85,9 @@ def create_local_mcp_server(bank_id: str, memory=None) -> FastMCP:
     """
     # Import here to avoid slow startup if just checking --help
     from hindsight_api import MemoryEngine
+    from hindsight_api.engine.memory_engine import Budget
+    from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES
+    from hindsight_api.models import RequestContext
 
     # Create memory engine with pg0 embedded database if not provided
     if memory is None:
@@ -102,17 +105,55 @@ def create_local_mcp_server(bank_id: str, memory=None) -> FastMCP:
 
     mcp = FastMCP("hindsight")
 
-    # Configure and register tools using shared module
-    config = MCPToolsConfig(
-        bank_id_resolver=lambda: bank_id,
-        include_bank_id_param=False,  # Local MCP uses fixed bank_id
-        tools={"retain", "recall"},  # Local MCP only has retain and recall
-        retain_description=retain_description,
-        recall_description=recall_description,
-        retain_fire_and_forget=True,  # Local MCP uses fire-and-forget pattern
-    )
+    @mcp.tool(description=retain_description)
+    async def retain(content: str, context: str = "general") -> dict:
+        """
+        Args:
+            content: The fact/memory to store (be specific and include relevant details)
+            context: Category for the memory (e.g., 'preferences', 'work', 'hobbies', 'family'). Default: 'general'
+        """
+        import asyncio
 
-    register_mcp_tools(mcp, memory, config)
+        async def _retain():
+            try:
+                await memory.retain_batch_async(
+                    bank_id=bank_id,
+                    contents=[{"content": content, "context": context}],
+                    request_context=RequestContext(),
+                )
+            except Exception as e:
+                logger.error(f"Error storing memory: {e}", exc_info=True)
+
+        # Fire and forget - don't block on memory storage
+        asyncio.create_task(_retain())
+        return {"status": "accepted", "message": "Memory storage initiated"}
+
+    @mcp.tool(description=recall_description)
+    async def recall(query: str, max_tokens: int = 4096, budget: str = "low") -> dict:
+        """
+        Args:
+            query: Natural language search query (e.g., "user's food preferences", "what projects is user working on")
+            max_tokens: Maximum tokens to return in results (default: 4096)
+            budget: Search budget level - "low", "mid", or "high" (default: "low")
+        """
+        try:
+            # Map string budget to enum
+            budget_map = {"low": Budget.LOW, "mid": Budget.MID, "high": Budget.HIGH}
+            budget_enum = budget_map.get(budget.lower(), Budget.LOW)
+
+            search_result = await memory.recall_async(
+                bank_id=bank_id,
+                query=query,
+                fact_type=list(VALID_RECALL_FACT_TYPES),
+                budget=budget_enum,
+                max_tokens=max_tokens,
+                request_context=RequestContext(),
+            )
+
+            return search_result.model_dump()
+        except Exception as e:
+            logger.error(f"Error searching: {e}", exc_info=True)
+            return {"error": str(e), "results": []}
 
     return mcp
 

hindsight-api/hindsight_api/mcp_tools.py

@@ -1,494 +0,0 @@
-"""Shared MCP tool implementations for Hindsight.
-
-This module provides the core tool logic used by both:
-- mcp_local.py (stdio transport for Claude Code)
-- api/mcp.py (HTTP transport for API server)
-"""
-
-import json
-import logging
-from dataclasses import dataclass
-from datetime import datetime
-from typing import Any, Callable
-
-from fastmcp import FastMCP
-
-from hindsight_api import MemoryEngine
-from hindsight_api.config import (
-    DEFAULT_MCP_RECALL_DESCRIPTION,
-    DEFAULT_MCP_RETAIN_DESCRIPTION,
-)
-from hindsight_api.engine.memory_engine import Budget
-from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES
-from hindsight_api.models import RequestContext
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class MCPToolsConfig:
-    """Configuration for MCP tools registration."""
-
-    # How to resolve bank_id for operations
-    bank_id_resolver: Callable[[], str | None]
-
-    # Whether to include bank_id as a parameter on tools (for multi-bank support)
-    include_bank_id_param: bool = False
-
-    # Which tools to register
-    tools: set[str] | None = None  # None means all tools
-
-    # Custom descriptions (if None, uses defaults)
-    retain_description: str | None = None
-    recall_description: str | None = None
-
-    # Retain behavior
-    retain_fire_and_forget: bool = False  # If True, use asyncio.create_task pattern
-
-
-def parse_timestamp(timestamp: str) -> datetime | None:
-    """Parse an ISO format timestamp string.
-
-    Args:
-        timestamp: ISO format timestamp (e.g., '2024-01-15T10:30:00Z')
-
-    Returns:
-        Parsed datetime or None if invalid
-
-    Raises:
-        ValueError: If timestamp format is invalid
-    """
-    try:
-        return datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
-    except ValueError as e:
-        raise ValueError(
-            f"Invalid timestamp format '{timestamp}'. "
-            "Expected ISO format like '2024-01-15T10:30:00' or '2024-01-15T10:30:00Z'"
-        ) from e
-
-
-def build_content_dict(
-    content: str,
-    context: str,
-    timestamp: str | None = None,
-) -> tuple[dict[str, Any], str | None]:
-    """Build a content dict for retain operations.
-
-    Args:
-        content: The memory content
-        context: Category for the memory
-        timestamp: Optional ISO timestamp
-
-    Returns:
-        Tuple of (content_dict, error_message). error_message is None if successful.
-    """
-    content_dict: dict[str, Any] = {"content": content, "context": context}
-
-    if timestamp:
-        try:
-            parsed_timestamp = parse_timestamp(timestamp)
-            content_dict["event_date"] = parsed_timestamp
-        except ValueError as e:
-            return {}, str(e)
-
-    return content_dict, None
-
-
-def register_mcp_tools(
-    mcp: FastMCP,
-    memory: MemoryEngine,
-    config: MCPToolsConfig,
-) -> None:
-    """Register MCP tools on a FastMCP server.
-
-    Args:
-        mcp: FastMCP server instance
-        memory: MemoryEngine instance
-        config: Tool configuration
-    """
-    tools_to_register = config.tools or {"retain", "recall", "reflect", "list_banks", "create_bank"}
-
-    if "retain" in tools_to_register:
-        _register_retain(mcp, memory, config)
-
-    if "recall" in tools_to_register:
-        _register_recall(mcp, memory, config)
-
-    if "reflect" in tools_to_register:
-        _register_reflect(mcp, memory, config)
-
-    if "list_banks" in tools_to_register:
-        _register_list_banks(mcp, memory, config)
-
-    if "create_bank" in tools_to_register:
-        _register_create_bank(mcp, memory, config)
-
-
-def _register_retain(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig) -> None:
-    """Register the retain tool."""
-    description = config.retain_description or DEFAULT_MCP_RETAIN_DESCRIPTION
-
-    if config.include_bank_id_param:
-        if config.retain_fire_and_forget:
-
-            @mcp.tool(description=description)
-            async def retain(
-                content: str,
-                context: str = "general",
-                timestamp: str | None = None,
-                bank_id: str | None = None,
-            ) -> dict:
-                """
-                Args:
-                    content: The fact/memory to store (be specific and include relevant details)
-                    context: Category for the memory (e.g., 'preferences', 'work', 'hobbies', 'family'). Default: 'general'
-                    timestamp: When this event/fact occurred (ISO format, e.g., '2024-01-15T10:30:00Z'). Useful for timeline tracking.
-                    bank_id: Optional bank to store in (defaults to session bank). Use for cross-bank operations.
-                """
-                import asyncio
-
-                target_bank = bank_id or config.bank_id_resolver()
-                if target_bank is None:
-                    return {"status": "error", "message": "No bank_id configured"}
-
-                content_dict, error = build_content_dict(content, context, timestamp)
-                if error:
-                    return {"status": "error", "message": error}
-
-                async def _retain():
-                    try:
-                        await memory.retain_batch_async(
-                            bank_id=target_bank,
-                            contents=[content_dict],
-                            request_context=RequestContext(),
-                        )
-                    except Exception as e:
-                        logger.error(f"Error storing memory: {e}", exc_info=True)
-
-                asyncio.create_task(_retain())
-                return {"status": "accepted", "message": "Memory storage initiated"}
-
-        else:
-
-            @mcp.tool(description=description)
-            async def retain(
-                content: str,
-                context: str = "general",
-                timestamp: str | None = None,
-                async_processing: bool = True,
-                bank_id: str | None = None,
-            ) -> str:
-                """
-                Args:
-                    content: The fact/memory to store (be specific and include relevant details)
-                    context: Category for the memory (e.g., 'preferences', 'work', 'hobbies', 'family'). Default: 'general'
-                    timestamp: When this event/fact occurred (ISO format, e.g., '2024-01-15T10:30:00Z'). Useful for timeline tracking.
-                    async_processing: If True, queue for background processing and return immediately. If False, wait for completion. Default: True
-                    bank_id: Optional bank to store in (defaults to session bank). Use for cross-bank operations.
-                """
-                try:
-                    target_bank = bank_id or config.bank_id_resolver()
-                    if target_bank is None:
-                        return "Error: No bank_id configured"
-
-                    content_dict, error = build_content_dict(content, context, timestamp)
-                    if error:
-                        return f"Error: {error}"
-
-                    contents = [content_dict]
-                    if async_processing:
-                        result = await memory.submit_async_retain(
-                            bank_id=target_bank, contents=contents, request_context=RequestContext()
-                        )
-                        return f"Memory queued for background processing (operation_id: {result.get('operation_id', 'N/A')})"
-                    else:
-                        await memory.retain_batch_async(
-                            bank_id=target_bank,
-                            contents=contents,
-                            request_context=RequestContext(),
-                        )
-                        return f"Memory stored successfully in bank '{target_bank}'"
-                except Exception as e:
-                    logger.error(f"Error storing memory: {e}", exc_info=True)
-                    return f"Error: {str(e)}"
-
-    else:
-        # No bank_id param - use fixed bank from resolver
-
-        @mcp.tool(description=description)
-        async def retain(
-            content: str,
-            context: str = "general",
-            timestamp: str | None = None,
-        ) -> dict:
-            """
-            Args:
-                content: The fact/memory to store (be specific and include relevant details)
-                context: Category for the memory (e.g., 'preferences', 'work', 'hobbies', 'family'). Default: 'general'
-                timestamp: When this event/fact occurred (ISO format, e.g., '2024-01-15T10:30:00Z'). Useful for timeline tracking.
-            """
-            import asyncio
-
-            target_bank = config.bank_id_resolver()
-            if target_bank is None:
-                return {"status": "error", "message": "No bank_id configured"}
-
-            content_dict, error = build_content_dict(content, context, timestamp)
-            if error:
-                return {"status": "error", "message": error}
-
-            async def _retain():
-                try:
-                    await memory.retain_batch_async(
-                        bank_id=target_bank,
-                        contents=[content_dict],
-                        request_context=RequestContext(),
-                    )
-                except Exception as e:
-                    logger.error(f"Error storing memory: {e}", exc_info=True)
-
-            asyncio.create_task(_retain())
-            return {"status": "accepted", "message": "Memory storage initiated"}
-
-
-def _register_recall(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig) -> None:
-    """Register the recall tool."""
-    description = config.recall_description or DEFAULT_MCP_RECALL_DESCRIPTION
-
-    if config.include_bank_id_param:
-
-        @mcp.tool(description=description)
-        async def recall(
-            query: str,
-            max_tokens: int = 4096,
-            bank_id: str | None = None,
-        ) -> str | dict:
-            """
-            Args:
-                query: Natural language search query (e.g., "user's food preferences", "what projects is user working on")
-                max_tokens: Maximum tokens to return in results (default: 4096)
-                bank_id: Optional bank to search in (defaults to session bank). Use for cross-bank operations.
-            """
-            try:
-                target_bank = bank_id or config.bank_id_resolver()
-                if target_bank is None:
-                    return "Error: No bank_id configured"
-
-                recall_result = await memory.recall_async(
-                    bank_id=target_bank,
-                    query=query,
-                    fact_type=list(VALID_RECALL_FACT_TYPES),
-                    budget=Budget.HIGH,
-                    max_tokens=max_tokens,
-                    request_context=RequestContext(),
-                )
-
-                return recall_result.model_dump_json(indent=2)
-            except Exception as e:
-                logger.error(f"Error searching: {e}", exc_info=True)
-                return f'{{"error": "{e}", "results": []}}'
-
-    else:
-
-        @mcp.tool(description=description)
-        async def recall(
-            query: str,
-            max_tokens: int = 4096,
-        ) -> dict:
-            """
-            Args:
-                query: Natural language search query (e.g., "user's food preferences", "what projects is user working on")
-                max_tokens: Maximum tokens to return in results (default: 4096)
-            """
-            try:
-                target_bank = config.bank_id_resolver()
-                if target_bank is None:
-                    return {"error": "No bank_id configured", "results": []}
-
-                recall_result = await memory.recall_async(
-                    bank_id=target_bank,
-                    query=query,
-                    fact_type=list(VALID_RECALL_FACT_TYPES),
-                    budget=Budget.HIGH,
-                    max_tokens=max_tokens,
-                    request_context=RequestContext(),
-                )
-
-                return recall_result.model_dump()
-            except Exception as e:
-                logger.error(f"Error searching: {e}", exc_info=True)
-                return {"error": str(e), "results": []}
-
-
-def _register_reflect(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig) -> None:
-    """Register the reflect tool."""
-
-    if config.include_bank_id_param:
-
-        @mcp.tool()
-        async def reflect(
-            query: str,
-            context: str | None = None,
-            budget: str = "low",
-            bank_id: str | None = None,
-        ) -> str:
-            """
-            Generate thoughtful analysis by synthesizing stored memories with the bank's personality.
-
-            WHEN TO USE THIS TOOL:
-            Use reflect when you need reasoned analysis, not just fact retrieval. This tool
-            thinks through the question using everything the bank knows and its personality traits.
-
-            EXAMPLES OF GOOD QUERIES:
-            - "What patterns have emerged in how I approach debugging?"
-            - "Based on my past decisions, what architectural style do I prefer?"
-            - "What might be the best approach for this problem given what you know about me?"
-            - "How should I prioritize these tasks based on my goals?"
-
-            HOW IT DIFFERS FROM RECALL:
-            - recall: Returns raw facts matching your search (fast lookup)
-            - reflect: Reasons across memories to form a synthesized answer (deeper analysis)
-
-            Use recall for "what did I say about X?" and reflect for "what should I do about X?"
-
-            Args:
-                query: The question or topic to reflect on
-                context: Optional context about why this reflection is needed
-                budget: Search budget - 'low', 'mid', or 'high' (default: 'low')
-                bank_id: Optional bank to reflect in (defaults to session bank). Use for cross-bank operations.
-            """
-            try:
-                target_bank = bank_id or config.bank_id_resolver()
-                if target_bank is None:
-                    return "Error: No bank_id configured"
-
-                budget_map = {"low": Budget.LOW, "mid": Budget.MID, "high": Budget.HIGH}
-                budget_enum = budget_map.get(budget.lower(), Budget.LOW)
-
-                reflect_result = await memory.reflect_async(
-                    bank_id=target_bank,
-                    query=query,
-                    budget=budget_enum,
-                    context=context,
-                    request_context=RequestContext(),
-                )
-
-                return reflect_result.model_dump_json(indent=2)
-            except Exception as e:
-                logger.error(f"Error reflecting: {e}", exc_info=True)
-                return f'{{"error": "{e}", "text": ""}}'
-
-    else:
-
-        @mcp.tool()
-        async def reflect(
-            query: str,
-            context: str | None = None,
-            budget: str = "low",
-        ) -> dict:
-            """
-            Generate thoughtful analysis by synthesizing stored memories with the bank's personality.
-
-            WHEN TO USE THIS TOOL:
-            Use reflect when you need reasoned analysis, not just fact retrieval. This tool
-            thinks through the question using everything the bank knows and its personality traits.
-
-            EXAMPLES OF GOOD QUERIES:
-            - "What patterns have emerged in how I approach debugging?"
-            - "Based on my past decisions, what architectural style do I prefer?"
-            - "What might be the best approach for this problem given what you know about me?"
-            - "How should I prioritize these tasks based on my goals?"
-
-            HOW IT DIFFERS FROM RECALL:
-            - recall: Returns raw facts matching your search (fast lookup)
-            - reflect: Reasons across memories to form a synthesized answer (deeper analysis)
-
-            Use recall for "what did I say about X?" and reflect for "what should I do about X?"
-
-            Args:
-                query: The question or topic to reflect on
-                context: Optional context about why this reflection is needed
-                budget: Search budget - 'low', 'mid', or 'high' (default: 'low')
-            """
-            try:
-                target_bank = config.bank_id_resolver()
-                if target_bank is None:
-                    return {"error": "No bank_id configured", "text": ""}
-
-                budget_map = {"low": Budget.LOW, "mid": Budget.MID, "high": Budget.HIGH}
-                budget_enum = budget_map.get(budget.lower(), Budget.LOW)
-
-                reflect_result = await memory.reflect_async(
-                    bank_id=target_bank,
-                    query=query,
-                    budget=budget_enum,
-                    context=context,
-                    request_context=RequestContext(),
-                )
-
-                return reflect_result.model_dump()
-            except Exception as e:
-                logger.error(f"Error reflecting: {e}", exc_info=True)
-                return {"error": str(e), "text": ""}
-
-
-def _register_list_banks(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig) -> None:
-    """Register the list_banks tool."""
-
-    @mcp.tool()
-    async def list_banks() -> str:
-        """
-        List all available memory banks.
-
-        Use this tool to discover what memory banks exist in the system.
-        Each bank is an isolated memory store (like a separate "brain").
-
-        Returns:
-            JSON list of banks with their IDs, names, dispositions, and missions.
-        """
-        try:
-            banks = await memory.list_banks(request_context=RequestContext())
-            return json.dumps({"banks": banks}, indent=2)
-        except Exception as e:
-            logger.error(f"Error listing banks: {e}", exc_info=True)
-            return f'{{"error": "{e}", "banks": []}}'
-
-
-def _register_create_bank(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig) -> None:
-    """Register the create_bank tool."""
-
-    @mcp.tool()
-    async def create_bank(bank_id: str, name: str | None = None, mission: str | None = None) -> str:
-        """
-        Create a new memory bank or get an existing one.
-
-        Memory banks are isolated stores - each one is like a separate "brain" for a user/agent.
-        Banks are auto-created with default settings if they don't exist.
-
-        Args:
-            bank_id: Unique identifier for the bank (e.g., 'user-123', 'agent-alpha')
-            name: Optional human-friendly name for the bank
-            mission: Optional mission describing who the agent is and what they're trying to accomplish
-        """
-        try:
-            # get_bank_profile auto-creates bank if it doesn't exist
-            profile = await memory.get_bank_profile(bank_id, request_context=RequestContext())
-
-            # Update name/mission if provided
-            if name is not None or mission is not None:
-                await memory.update_bank(
-                    bank_id,
-                    name=name,
-                    mission=mission,
-                    request_context=RequestContext(),
-                )
-                # Fetch updated profile
-                profile = await memory.get_bank_profile(bank_id, request_context=RequestContext())
-
-            # Serialize disposition if it's a Pydantic model
-            if "disposition" in profile and hasattr(profile["disposition"], "model_dump"):
-                profile["disposition"] = profile["disposition"].model_dump()
-            return json.dumps(profile, indent=2)
-        except Exception as e:
-            logger.error(f"Error creating bank: {e}", exc_info=True)
-            return f'{{"error": "{e}"}}'

hindsight-api/hindsight_api/worker/main.py

@@ -181,8 +181,6 @@ def main():
         nonlocal memory, poller
         import uvicorn
 
-        from ..extensions import TenantExtension, load_extension
-
         # Initialize MemoryEngine
         # Workers use SyncTaskBackend because they execute tasks directly,
         # they don't need to store tasks (they poll from DB)
@@ -195,15 +193,7 @@ def main():
 
         print(f"Database connected: {config.database_url}")
 
-        # Load tenant extension for dynamic schema discovery
-        tenant_extension = load_extension("TENANT", TenantExtension)
-
-        if tenant_extension:
-            print("Tenant extension loaded - schemas will be discovered dynamically on each poll")
-        else:
-            print("No tenant extension configured, using public schema only")
-
-        # Create a single poller that handles all schemas dynamically
+        # Create and start the poller
         poller = WorkerPoller(
             pool=memory._pool,
             worker_id=args.worker_id,
@@ -211,7 +201,6 @@ def main():
             poll_interval_ms=args.poll_interval,
             batch_size=args.batch_size,
             max_retries=args.max_retries,
-            tenant_extension=tenant_extension,
         )
 
         # Create the HTTP app for metrics/health

hindsight-api/hindsight_api/worker/poller.py

@@ -8,22 +8,15 @@ FOR UPDATE SKIP LOCKED for safe concurrent claiming.
 import asyncio
 import json
 import logging
-import time
 import traceback
 from collections.abc import Awaitable, Callable
-from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     import asyncpg
 
-    from hindsight_api.extensions.tenant import TenantExtension
-
 logger = logging.getLogger(__name__)
 
-# Progress logging interval in seconds
-PROGRESS_LOG_INTERVAL = 30
-
 
 def fq_table(table: str, schema: str | None = None) -> str:
     """Get fully-qualified table name with optional schema prefix."""
@@ -32,23 +25,12 @@ def fq_table(table: str, schema: str | None = None) -> str:
     return table
 
 
-@dataclass
-class ClaimedTask:
-    """A task claimed from the database with its schema context."""
-
-    operation_id: str
-    task_dict: dict[str, Any]
-    schema: str | None
-
-
 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.
-
-    Supports dynamic multi-tenant discovery via tenant_extension.
     """
 
     def __init__(
@@ -60,7 +42,6 @@ class WorkerPoller:
         batch_size: int = 10,
         max_retries: int = 3,
         schema: str | None = None,
-        tenant_extension: "TenantExtension | None" = None,
     ):
         """
         Initialize the worker poller.
@@ -72,9 +53,7 @@ class WorkerPoller:
             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 single-tenant support (ignored if tenant_extension is set)
-            tenant_extension: Extension for dynamic multi-tenant discovery. If set, list_tenants()
-                            is called on each poll cycle to discover schemas dynamically.
+            schema: Database schema for multi-tenant support (optional)
         """
         self._pool = pool
         self._worker_id = worker_id
@@ -83,83 +62,35 @@ class WorkerPoller:
         self._batch_size = batch_size
         self._max_retries = max_retries
         self._schema = schema
-        self._tenant_extension = tenant_extension
         self._shutdown = asyncio.Event()
         self._current_tasks: set[asyncio.Task] = set()
         self._in_flight_count = 0
         self._in_flight_lock = asyncio.Lock()
-        self._last_progress_log = 0.0
-        self._tasks_completed_since_log = 0
-        # Track active tasks locally: operation_id -> (op_type, bank_id, schema)
-        self._active_tasks: dict[str, tuple[str, str, str | None]] = {}
 
-    async def _get_schemas(self) -> list[str | None]:
-        """Get list of schemas to poll. Returns [None] for public schema."""
-        if self._tenant_extension is not None:
-            tenants = await self._tenant_extension.list_tenants()
-            # Convert "public" to None for SQL compatibility, keep others as-is
-            return [t.schema if t.schema != "public" else None for t in tenants]
-        # Single schema mode
-        return [self._schema]
-
-    async def claim_batch(self) -> list[ClaimedTask]:
+    async def claim_batch(self) -> list[tuple[str, dict[str, Any]]]:
         """
-        Claim up to batch_size pending tasks atomically across all tenant schemas.
+        Claim up to batch_size pending tasks atomically.
 
         Uses FOR UPDATE SKIP LOCKED to ensure no conflicts with other workers.
 
-        For consolidation tasks specifically, skips pending tasks if there's already
-        a processing consolidation for the same bank (to avoid duplicate work).
-
-        If tenant_extension is configured, dynamically discovers schemas on each call.
-
         Returns:
-            List of ClaimedTask objects containing operation_id, task_dict, and schema
+            List of tuples (operation_id, task_dict)
         """
-        schemas = await self._get_schemas()
-        all_tasks: list[ClaimedTask] = []
-        remaining_batch = self._batch_size
-
-        for schema in schemas:
-            if remaining_batch <= 0:
-                break
-
-            tasks = await self._claim_batch_for_schema(schema, remaining_batch)
-            all_tasks.extend(tasks)
-            remaining_batch -= len(tasks)
-
-        return all_tasks
-
-    async def _claim_batch_for_schema(self, schema: str | None, limit: int) -> list[ClaimedTask]:
-        """Claim tasks from a specific schema."""
-        table = fq_table("async_operations", schema)
+        table = fq_table("async_operations", self._schema)
 
         async with self._pool.acquire() as conn:
             async with conn.transaction():
                 # Select and lock pending tasks
-                # For consolidation: skip if same bank already has one processing
                 rows = await conn.fetch(
                     f"""
                     SELECT operation_id, task_payload
-                    FROM {table} AS pending
+                    FROM {table}
                     WHERE status = 'pending' AND task_payload IS NOT NULL
-                    AND (
-                        -- Non-consolidation tasks: always claimable
-                        operation_type != 'consolidation'
-                        OR
-                        -- Consolidation: only if no other consolidation processing for same bank
-                        NOT EXISTS (
-                            SELECT 1 FROM {table} AS processing
-                            WHERE processing.bank_id = pending.bank_id
-                            AND processing.operation_type = 'consolidation'
-                            AND processing.status = 'processing'
-                        )
-                    )
                     ORDER BY created_at
                     LIMIT $1
                     FOR UPDATE SKIP LOCKED
                     """,
-                    limit,
+                    self._batch_size,
                 )
 
                 if not rows:
@@ -177,19 +108,12 @@ class WorkerPoller:
                     operation_ids,
                 )
 
-                # Parse and return task payloads with schema context
-                return [
-                    ClaimedTask(
-                        operation_id=str(row["operation_id"]),
-                        task_dict=json.loads(row["task_payload"]),
-                        schema=schema,
-                    )
-                    for row in rows
-                ]
+                # 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, schema: str | None):
+    async def _mark_completed(self, operation_id: str):
         """Mark a task as completed."""
-        table = fq_table("async_operations", schema)
+        table = fq_table("async_operations", self._schema)
         await self._pool.execute(
             f"""
             UPDATE {table}
@@ -199,9 +123,9 @@ class WorkerPoller:
             operation_id,
         )
 
-    async def _mark_failed(self, operation_id: str, error_message: str, schema: str | None):
+    async def _mark_failed(self, operation_id: str, error_message: str):
         """Mark a task as failed with error message."""
-        table = fq_table("async_operations", schema)
+        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(
@@ -214,9 +138,9 @@ class WorkerPoller:
             error_message,
         )
 
-    async def _retry_or_fail(self, operation_id: str, error_message: str, schema: str | None):
+    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", schema)
+        table = fq_table("async_operations", self._schema)
 
         # Get current retry count
         row = await self._pool.fetchrow(
@@ -233,7 +157,7 @@ class WorkerPoller:
         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}", schema
+                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:
@@ -249,68 +173,20 @@ class WorkerPoller:
             )
             logger.warning(f"Task {operation_id} failed, will retry (attempt {retry_count + 1}/{self._max_retries})")
 
-    async def execute_task(self, task: ClaimedTask):
+    async def execute_task(self, operation_id: str, task_dict: dict[str, Any]):
         """Execute a single task and update its status."""
-        task_type = task.task_dict.get("type", "unknown")
-        bank_id = task.task_dict.get("bank_id", "unknown")
-
-        # Track this task as active
-        async with self._in_flight_lock:
-            self._active_tasks[task.operation_id] = (task_type, bank_id, task.schema)
+        task_type = task_dict.get("type", "unknown")
+        bank_id = task_dict.get("bank_id", "unknown")
 
         try:
-            schema_info = f", schema={task.schema}" if task.schema else ""
-            logger.debug(f"Executing task {task.operation_id} (type={task_type}, bank={bank_id}{schema_info})")
-            # Pass schema to executor so it can set the correct context
-            if task.schema:
-                task.task_dict["_schema"] = task.schema
-            await self._executor(task.task_dict)
-            await self._mark_completed(task.operation_id, task.schema)
-            logger.debug(f"Task {task.operation_id} completed successfully")
+            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 {task.operation_id} failed: {e}")
-            await self._retry_or_fail(task.operation_id, error_msg, task.schema)
-        finally:
-            # Remove from active tasks
-            async with self._in_flight_lock:
-                self._active_tasks.pop(task.operation_id, None)
-
-    async def recover_own_tasks(self) -> int:
-        """
-        Recover tasks that were assigned to this worker but not completed.
-
-        This handles the case where a worker crashes while processing tasks.
-        On startup, we reset any tasks stuck in 'processing' for this worker_id
-        back to 'pending' so they can be picked up again.
-
-        If tenant_extension is configured, recovers across all tenant schemas.
-
-        Returns:
-            Number of tasks recovered
-        """
-        schemas = await self._get_schemas()
-        total_count = 0
-
-        for schema in schemas:
-            table = fq_table("async_operations", schema)
-
-            result = await self._pool.execute(
-                f"""
-                UPDATE {table}
-                SET status = 'pending', worker_id = NULL, claimed_at = NULL, updated_at = now()
-                WHERE status = 'processing' AND worker_id = $1
-                """,
-                self._worker_id,
-            )
-
-            # Parse "UPDATE N" to get count
-            count = int(result.split()[-1]) if result else 0
-            total_count += count
-
-        if total_count > 0:
-            logger.info(f"Worker {self._worker_id} recovered {total_count} stale tasks from previous run")
-        return total_count
+            logger.error(f"Task {operation_id} failed: {e}")
+            await self._retry_or_fail(operation_id, error_msg)
 
     async def run(self):
         """
@@ -318,32 +194,22 @@ class WorkerPoller:
 
         Continuously polls for pending tasks, claims them, and executes them
         until shutdown is signaled.
-
-        If tenant_extension is configured, dynamically discovers schemas on each poll.
         """
-        # Recover any tasks from a previous crash before starting
-        await self.recover_own_tasks()
-
         logger.info(f"Worker {self._worker_id} starting polling loop")
 
         while not self._shutdown.is_set():
             try:
-                # Claim a batch of tasks (across all tenant schemas if configured)
+                # Claim a batch of tasks
                 tasks = await self.claim_batch()
 
                 if tasks:
                     # Log batch info
-                    task_types: dict[str, int] = {}
-                    schemas_seen: set[str | None] = set()
-                    for task in tasks:
-                        t = task.task_dict.get("type", "unknown")
+                    task_types = {}
+                    for _, task_dict in tasks:
+                        t = task_dict.get("type", "unknown")
                         task_types[t] = task_types.get(t, 0) + 1
-                        schemas_seen.add(task.schema)
                     types_str = ", ".join(f"{k}:{v}" for k, v in task_types.items())
-                    schemas_str = ", ".join(s or "public" for s in schemas_seen)
-                    logger.info(
-                        f"Worker {self._worker_id} claimed {len(tasks)} tasks: {types_str} (schemas: {schemas_str})"
-                    )
+                    logger.info(f"Worker {self._worker_id} claimed {len(tasks)} tasks: {types_str}")
 
                     # Track in-flight tasks
                     async with self._in_flight_lock:
@@ -352,7 +218,7 @@ class WorkerPoller:
                     # Execute tasks concurrently
                     try:
                         await asyncio.gather(
-                            *[self.execute_task(task) for task in tasks],
+                            *[self.execute_task(op_id, task_dict) for op_id, task_dict in tasks],
                             return_exceptions=True,
                         )
                     finally:
@@ -368,9 +234,6 @@ class WorkerPoller:
                     except asyncio.TimeoutError:
                         pass  # Normal timeout, continue polling
 
-                # Log progress stats periodically
-                await self._log_progress_if_due()
-
             except asyncio.CancelledError:
                 logger.info(f"Worker {self._worker_id} polling loop cancelled")
                 break
@@ -407,74 +270,6 @@ class WorkerPoller:
 
         logger.warning(f"Worker {self._worker_id} shutdown timeout after {timeout}s")
 
-    async def _log_progress_if_due(self):
-        """Log progress stats every PROGRESS_LOG_INTERVAL seconds."""
-        now = time.time()
-        if now - self._last_progress_log < PROGRESS_LOG_INTERVAL:
-            return
-
-        self._last_progress_log = now
-
-        try:
-            # Get local active tasks (this worker only)
-            async with self._in_flight_lock:
-                in_flight = self._in_flight_count
-                active_tasks = dict(self._active_tasks)  # Copy to avoid holding lock
-
-            # Build local processing breakdown grouped by (op_type, bank_id)
-            task_groups: dict[tuple[str, str], int] = {}
-            for op_type, bank_id, _ in active_tasks.values():
-                key = (op_type, bank_id)
-                task_groups[key] = task_groups.get(key, 0) + 1
-
-            processing_info = [f"{op}:{bank}({cnt})" for (op, bank), cnt in task_groups.items()]
-            processing_str = ", ".join(processing_info[:10]) if processing_info else "none"
-            if len(processing_info) > 10:
-                processing_str += f" +{len(processing_info) - 10} more"
-
-            # Get global stats from DB across all schemas
-            schemas = await self._get_schemas()
-            global_pending = 0
-            all_worker_counts: dict[str, int] = {}
-
-            async with self._pool.acquire() as conn:
-                for schema in schemas:
-                    table = fq_table("async_operations", schema)
-
-                    row = await conn.fetchrow(f"SELECT COUNT(*) as count FROM {table} WHERE status = 'pending'")
-                    global_pending += row["count"] if row else 0
-
-                    # Get processing breakdown by worker
-                    worker_rows = await conn.fetch(
-                        f"""
-                        SELECT worker_id, COUNT(*) as count
-                        FROM {table}
-                        WHERE status = 'processing'
-                        GROUP BY worker_id
-                        """
-                    )
-                    for wr in worker_rows:
-                        wid = wr["worker_id"] or "unknown"
-                        all_worker_counts[wid] = all_worker_counts.get(wid, 0) + wr["count"]
-
-            # Format other workers' processing counts
-            other_workers = []
-            for wid, cnt in all_worker_counts.items():
-                if wid != self._worker_id:
-                    other_workers.append(f"{wid}:{cnt}")
-            others_str = ", ".join(other_workers) if other_workers else "none"
-
-            schemas_str = ", ".join(s or "public" for s in schemas)
-            logger.info(
-                f"[WORKER_STATS] worker={self._worker_id} in_flight={in_flight} | "
-                f"global: pending={global_pending} (schemas: {schemas_str}) | "
-                f"others: {others_str} | "
-                f"my_active: {processing_str}"
-            )
-
-        except Exception as e:
-            logger.debug(f"Failed to log progress stats: {e}")
-
     @property
     def worker_id(self) -> str:
         """Get the worker ID."""

hindsight-api/tests/test_custom_embedding_dimension.py

@@ -9,18 +9,18 @@ Includes tests for:
 
 import asyncio
 import os
-from datetime import datetime
-
 import pytest
+from datetime import datetime
 from sqlalchemy import create_engine, text
 
 from hindsight_api import MemoryEngine, RequestContext
-from hindsight_api.engine.cross_encoder import CohereCrossEncoder, LocalSTCrossEncoder
-from hindsight_api.engine.embeddings import CohereEmbeddings, LocalSTEmbeddings, OpenAIEmbeddings
+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 TenantContext, TenantExtension
-from hindsight_api.migrations import ensure_embedding_dimension, run_migrations
+from hindsight_api.extensions import TenantExtension, TenantContext
+from hindsight_api.migrations import run_migrations, ensure_embedding_dimension
+
 
 # =============================================================================
 # Shared Utilities
@@ -36,11 +36,6 @@ class SchemaTenantExtension(TenantExtension):
     async def authenticate(self, request_context: RequestContext) -> TenantContext:
         return TenantContext(schema_name=self.schema_name)
 
-    async def list_tenants(self) -> list:
-        from hindsight_api.extensions.tenant import Tenant
-
-        return [Tenant(schema=self.schema_name)]
-
 
 def get_test_schema(prefix: str, worker_id: str) -> str:
     """Get unique schema name per xdist worker."""

hindsight-api/tests/test_emergent_filtering.py

@@ -0,0 +1,516 @@
+"""Tests for emergent entity filtering."""
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+
+from hindsight_api.engine.mental_models.emergent import (
+    build_mission_filter_prompt,
+    evaluate_emergent_models,
+    filter_candidates_by_mission,
+    MissionFilterResponse,
+    MissionFilterCandidate,
+)
+from hindsight_api.engine.mental_models.models import EmergentCandidate
+
+
+class TestBuildMissionFilterPrompt:
+    """Test prompt building for mission filtering."""
+
+    def test_prompt_contains_mission(self):
+        """Test that prompt includes the mission."""
+        candidates = [
+            EmergentCandidate(
+                name="Alice",
+                detection_method="named_entity_extraction",
+                mention_count=10,
+            )
+        ]
+        prompt = build_mission_filter_prompt("Be a PM for engineering team", candidates)
+        assert "Be a PM for engineering team" in prompt
+
+    def test_prompt_contains_candidates(self):
+        """Test that prompt includes all candidates."""
+        candidates = [
+            EmergentCandidate(
+                name="Alice Chen",
+                detection_method="named_entity_extraction",
+                mention_count=10,
+            ),
+            EmergentCandidate(
+                name="Project Phoenix",
+                detection_method="named_entity_extraction",
+                mention_count=5,
+            ),
+        ]
+        prompt = build_mission_filter_prompt("Track projects", candidates)
+        assert "Alice Chen" in prompt
+        assert "Project Phoenix" in prompt
+
+    def test_prompt_contains_rejection_guidance(self):
+        """Test that prompt contains guidance to reject generic entities."""
+        candidates = [
+            EmergentCandidate(
+                name="test",
+                detection_method="named_entity_extraction",
+                mention_count=1,
+            )
+        ]
+        prompt = build_mission_filter_prompt("Test mission", candidates)
+
+        # Should contain rejection guidance for generic terms
+        assert "promote=false" in prompt
+        assert "kids" in prompt  # Example of generic term to reject
+        assert "community" in prompt  # Example of abstract concept to reject
+        assert "motivation" in prompt  # Example of abstract concept to reject
+
+
+class TestFilterCandidatesByMission:
+    """Test the filter_candidates_by_mission function."""
+
+    @pytest.fixture
+    def mock_llm_config(self):
+        """Create a mock LLM config."""
+        config = MagicMock()
+        config.call = AsyncMock()
+        return config
+
+    async def test_empty_candidates(self, mock_llm_config):
+        """Test with empty candidate list."""
+        result = await filter_candidates_by_mission(
+            llm_config=mock_llm_config,
+            mission="Test mission",
+            candidates=[],
+        )
+        assert result == []
+        mock_llm_config.call.assert_not_called()
+
+    async def test_no_mission_keeps_all(self, mock_llm_config):
+        """Test that no mission keeps all candidates (skips filtering)."""
+        candidates = [
+            EmergentCandidate(
+                name="Alice",
+                detection_method="named_entity_extraction",
+                mention_count=10,
+            )
+        ]
+        result = await filter_candidates_by_mission(
+            llm_config=mock_llm_config,
+            mission="",  # Empty mission
+            candidates=candidates,
+        )
+        assert len(result) == 1
+        assert result[0].name == "Alice"
+        mock_llm_config.call.assert_not_called()
+
+    async def test_filters_by_promote_flag(self, mock_llm_config):
+        """Test that candidates are filtered by promote flag."""
+        candidates = [
+            EmergentCandidate(
+                name="Alice Chen",
+                detection_method="named_entity_extraction",
+                mention_count=10,
+            ),
+            EmergentCandidate(
+                name="community",
+                detection_method="named_entity_extraction",
+                mention_count=5,
+            ),
+        ]
+
+        # Mock LLM response - Alice is promoted, community is not
+        mock_llm_config.call.return_value = MissionFilterResponse(
+            candidates=[
+                MissionFilterCandidate(name="Alice Chen", promote=True, reason="Specific person"),
+                MissionFilterCandidate(name="community", promote=False, reason="Generic abstract concept"),
+            ]
+        )
+
+        result = await filter_candidates_by_mission(
+            llm_config=mock_llm_config,
+            mission="Be a PM for engineering team",
+            candidates=candidates,
+        )
+
+        assert len(result) == 1
+        assert result[0].name == "Alice Chen"
+
+    async def test_rejects_generic_entities(self, mock_llm_config):
+        """Test that generic entities are rejected."""
+        # These are all generic/abstract terms that should be rejected
+        generic_names = [
+            "user", "support", "community", "family", "motivation",
+            "photo", "gratitude", "difference", "volunteering",
+            "kids", "veterans", "impact", "kindness", "encouragement",
+            "education", "nature", "joy", "positivity", "inspiration",
+            "help", "commitment", "passion", "energy", "connection",
+        ]
+        candidates = [
+            EmergentCandidate(
+                name=name,
+                detection_method="named_entity_extraction",
+                mention_count=10,
+            )
+            for name in generic_names
+        ]
+
+        # Add some valid candidates
+        valid_candidates = [
+            EmergentCandidate(
+                name="John",
+                detection_method="named_entity_extraction",
+                mention_count=10,
+            ),
+            EmergentCandidate(
+                name="Maria",
+                detection_method="named_entity_extraction",
+                mention_count=8,
+            ),
+            EmergentCandidate(
+                name="Max",
+                detection_method="named_entity_extraction",
+                mention_count=6,
+            ),
+        ]
+        candidates.extend(valid_candidates)
+
+        # Mock LLM response - reject all generic, promote only specific names
+        response_candidates = [
+            MissionFilterCandidate(name=name, promote=False, reason="Generic/abstract term")
+            for name in generic_names
+        ]
+        response_candidates.extend([
+            MissionFilterCandidate(name=c.name, promote=True, reason="Specific person name")
+            for c in valid_candidates
+        ])
+
+        mock_llm_config.call.return_value = MissionFilterResponse(candidates=response_candidates)
+
+        result = await filter_candidates_by_mission(
+            llm_config=mock_llm_config,
+            mission="Be a health coach",
+            candidates=candidates,
+        )
+
+        # Should only have John, Maria, and Max
+        result_names = {c.name for c in result}
+        assert result_names == {"John", "Maria", "Max"}
+
+    async def test_accepts_specific_named_entities(self, mock_llm_config):
+        """Test that specific named entities are accepted."""
+        # These should all be accepted
+        valid_names = [
+            "Alice Chen",       # Full name
+            "Dr. Smith",        # Title + name
+            "John",             # First name (when it's clearly a person)
+            "Google",           # Organization
+            "Frontend Team",    # Named team
+            "Project Phoenix",  # Named project
+            "NYC Office",       # Named place
+            "Q4 Planning",      # Named event
+            "Sprint 23 Review", # Named meeting
+        ]
+        candidates = [
+            EmergentCandidate(
+                name=name,
+                detection_method="named_entity_extraction",
+                mention_count=10,
+            )
+            for name in valid_names
+        ]
+
+        # Mock LLM response - promote all
+        response_candidates = [
+            MissionFilterCandidate(name=name, promote=True, reason="Specific named entity")
+            for name in valid_names
+        ]
+        mock_llm_config.call.return_value = MissionFilterResponse(candidates=response_candidates)
+
+        result = await filter_candidates_by_mission(
+            llm_config=mock_llm_config,
+            mission="Be a PM for engineering team",
+            candidates=candidates,
+        )
+
+        # Should have all valid names
+        result_names = {c.name for c in result}
+        assert result_names == set(valid_names)
+
+    async def test_llm_error_rejects_all_candidates(self, mock_llm_config):
+        """Test that LLM errors result in rejecting all candidates (fail-safe)."""
+        candidates = [
+            EmergentCandidate(
+                name="Alice",
+                detection_method="named_entity_extraction",
+                mention_count=10,
+            )
+        ]
+
+        mock_llm_config.call.side_effect = Exception("LLM error")
+
+        result = await filter_candidates_by_mission(
+            llm_config=mock_llm_config,
+            mission="Test mission",
+            candidates=candidates,
+        )
+
+        # Should reject all candidates on error (fail-safe)
+        assert len(result) == 0
+
+    async def test_missing_candidate_in_response_is_rejected(self, mock_llm_config):
+        """Test that candidates not in LLM response are rejected by default."""
+        candidates = [
+            EmergentCandidate(
+                name="Alice",
+                detection_method="named_entity_extraction",
+                mention_count=10,
+            ),
+            EmergentCandidate(
+                name="Bob",
+                detection_method="named_entity_extraction",
+                mention_count=5,
+            ),
+        ]
+
+        # Mock LLM response - only includes Alice, not Bob
+        mock_llm_config.call.return_value = MissionFilterResponse(
+            candidates=[
+                MissionFilterCandidate(name="Alice", promote=True, reason="Specific person"),
+            ]
+        )
+
+        result = await filter_candidates_by_mission(
+            llm_config=mock_llm_config,
+            mission="Test mission",
+            candidates=candidates,
+        )
+
+        # Only Alice should be in result (Bob was missing from response, so rejected)
+        assert len(result) == 1
+        assert result[0].name == "Alice"
+
+
+class TestEvaluateEmergentModels:
+    """Test the evaluate_emergent_models function for cleanup of existing models."""
+
+    @pytest.fixture
+    def mock_llm_config(self):
+        """Create a mock LLM config."""
+        config = MagicMock()
+        config.call = AsyncMock()
+        return config
+
+    async def test_empty_models(self, mock_llm_config):
+        """Test with empty model list."""
+        result = await evaluate_emergent_models(
+            llm_config=mock_llm_config,
+            models=[],
+        )
+        assert result == []
+        mock_llm_config.call.assert_not_called()
+
+    async def test_removes_generic_models(self, mock_llm_config):
+        """Test that generic/abstract models are marked for removal."""
+        models = [
+            {"id": "id-kids", "name": "kids"},
+            {"id": "id-community", "name": "community"},
+            {"id": "id-motivation", "name": "motivation"},
+            {"id": "id-john", "name": "John"},
+            {"id": "id-maria", "name": "Maria"},
+        ]
+
+        # Mock LLM response - reject generic, keep specific names
+        mock_llm_config.call.return_value = MissionFilterResponse(
+            candidates=[
+                MissionFilterCandidate(name="kids", promote=False, reason="Generic category"),
+                MissionFilterCandidate(name="community", promote=False, reason="Abstract concept"),
+                MissionFilterCandidate(name="motivation", promote=False, reason="Abstract concept"),
+                MissionFilterCandidate(name="John", promote=True, reason="Person name"),
+                MissionFilterCandidate(name="Maria", promote=True, reason="Person name"),
+            ]
+        )
+
+        result = await evaluate_emergent_models(
+            llm_config=mock_llm_config,
+            models=models,
+        )
+
+        # Should return IDs of generic models to remove
+        assert set(result) == {"id-kids", "id-community", "id-motivation"}
+
+    async def test_keeps_specific_named_models(self, mock_llm_config):
+        """Test that specific named models are kept."""
+        models = [
+            {"id": "id-john", "name": "John"},
+            {"id": "id-google", "name": "Google"},
+            {"id": "id-project", "name": "Project Phoenix"},
+        ]
+
+        # Mock LLM response - keep all
+        mock_llm_config.call.return_value = MissionFilterResponse(
+            candidates=[
+                MissionFilterCandidate(name="John", promote=True, reason="Person name"),
+                MissionFilterCandidate(name="Google", promote=True, reason="Organization"),
+                MissionFilterCandidate(name="Project Phoenix", promote=True, reason="Named project"),
+            ]
+        )
+
+        result = await evaluate_emergent_models(
+            llm_config=mock_llm_config,
+            models=models,
+        )
+
+        # No models should be removed
+        assert result == []
+
+    async def test_llm_error_keeps_all_models(self, mock_llm_config):
+        """Test that LLM errors result in keeping all models (safe default)."""
+        models = [
+            {"id": "id-kids", "name": "kids"},
+            {"id": "id-john", "name": "John"},
+        ]
+
+        mock_llm_config.call.side_effect = Exception("LLM error")
+
+        result = await evaluate_emergent_models(
+            llm_config=mock_llm_config,
+            models=models,
+        )
+
+        # Should keep all models on error (return empty removal list)
+        assert result == []
+
+    async def test_missing_model_in_response_is_removed(self, mock_llm_config):
+        """Test that models not in LLM response are marked for removal."""
+        models = [
+            {"id": "id-alice", "name": "Alice"},
+            {"id": "id-bob", "name": "Bob"},
+        ]
+
+        # Mock LLM response - only includes Alice
+        mock_llm_config.call.return_value = MissionFilterResponse(
+            candidates=[
+                MissionFilterCandidate(name="Alice", promote=True, reason="Person name"),
+            ]
+        )
+
+        result = await evaluate_emergent_models(
+            llm_config=mock_llm_config,
+            models=models,
+        )
+
+        # Bob should be marked for removal (missing from response)
+        assert result == ["id-bob"]
+
+
+class TestRemovedEntitiesNotRepromoted:
+    """Test that entities removed by evaluation are not re-promoted.
+
+    This tests the fix for a bug where:
+    1. evaluate_emergent_models returns model IDs to remove (e.g., 'entity-maya')
+    2. We delete those models
+    3. detect_entity_candidates finds the same entities (now eligible since model was deleted)
+    4. filter_candidates_by_goal approves them (different LLM call)
+    5. BUG: We were re-promoting the same entities we just removed
+
+    The fix tracks removed entity_ids and excludes them from promotion.
+    """
+
+    async def test_removed_entity_ids_excluded_from_promotion(self):
+        """Test that entities whose models were removed are not re-promoted."""
+        from hindsight_api.engine.mental_models.models import EmergentCandidate
+
+        # Simulate the scenario from the bug:
+        # - existing_emergent has model 'entity-maya' with entity_id='uuid-maya'
+        # - evaluate_emergent_models says to remove 'entity-maya'
+        # - detect_entity_candidates returns 'Maya' with entity_id='uuid-maya' (now eligible)
+        # - filter_candidates_by_goal says to promote 'Maya'
+        # - But we should NOT promote because we just removed it
+
+        existing_emergent = [
+            {"id": "entity-maya", "name": "Maya", "entity_id": "uuid-maya"},
+            {"id": "entity-alex", "name": "Alex", "entity_id": "uuid-alex"},
+            {"id": "entity-john", "name": "John", "entity_id": "uuid-john"},  # This one will be kept
+        ]
+
+        # Models to remove (evaluate_emergent_models would return these)
+        models_to_remove = ["entity-maya", "entity-alex"]
+
+        # Build model_id -> entity_id mapping (this is what the fix does)
+        model_to_entity = {m["id"]: m.get("entity_id") for m in existing_emergent}
+
+        # Track removed entity_ids
+        removed_entity_ids: set[str] = set()
+        for model_id in models_to_remove:
+            entity_id = model_to_entity.get(model_id)
+            if entity_id:
+                removed_entity_ids.add(str(entity_id))
+
+        # Verify we tracked the right entity_ids
+        assert removed_entity_ids == {"uuid-maya", "uuid-alex"}
+
+        # Now simulate candidates that were detected (includes removed entities)
+        candidates = [
+            EmergentCandidate(
+                name="Maya", entity_id="uuid-maya", detection_method="named_entity", mention_count=10
+            ),
+            EmergentCandidate(
+                name="Alex", entity_id="uuid-alex", detection_method="named_entity", mention_count=8
+            ),
+            EmergentCandidate(
+                name="NewPerson", entity_id="uuid-new", detection_method="named_entity", mention_count=5
+            ),
+        ]
+
+        # Filter out candidates whose entity was just removed (the fix)
+        filtered_candidates = [c for c in candidates if c.entity_id not in removed_entity_ids]
+
+        # Only NewPerson should remain - Maya and Alex were removed and should not be re-promoted
+        assert len(filtered_candidates) == 1
+        assert filtered_candidates[0].name == "NewPerson"
+        assert filtered_candidates[0].entity_id == "uuid-new"
+
+    async def test_candidates_without_matching_removal_are_kept(self):
+        """Test that candidates not in the removed set are still promoted."""
+        from hindsight_api.engine.mental_models.models import EmergentCandidate
+
+        # No models removed
+        removed_entity_ids: set[str] = set()
+
+        candidates = [
+            EmergentCandidate(
+                name="Alice", entity_id="uuid-alice", detection_method="named_entity", mention_count=10
+            ),
+            EmergentCandidate(
+                name="Bob", entity_id="uuid-bob", detection_method="named_entity", mention_count=8
+            ),
+        ]
+
+        # Filter (should keep all since nothing was removed)
+        filtered_candidates = [c for c in candidates if c.entity_id not in removed_entity_ids]
+
+        assert len(filtered_candidates) == 2
+        assert {c.name for c in filtered_candidates} == {"Alice", "Bob"}
+
+    async def test_partial_removal_keeps_other_candidates(self):
+        """Test that only removed entities are excluded, others pass through."""
+        from hindsight_api.engine.mental_models.models import EmergentCandidate
+
+        # Only one entity removed
+        removed_entity_ids = {"uuid-removed"}
+
+        candidates = [
+            EmergentCandidate(
+                name="Removed", entity_id="uuid-removed", detection_method="named_entity", mention_count=10
+            ),
+            EmergentCandidate(
+                name="Kept1", entity_id="uuid-kept1", detection_method="named_entity", mention_count=8
+            ),
+            EmergentCandidate(
+                name="Kept2", entity_id="uuid-kept2", detection_method="named_entity", mention_count=5
+            ),
+        ]
+
+        filtered_candidates = [c for c in candidates if c.entity_id not in removed_entity_ids]
+
+        assert len(filtered_candidates) == 2
+        assert {c.name for c in filtered_candidates} == {"Kept1", "Kept2"}

hindsight-api/tests/test_extensions.py

@@ -17,6 +17,8 @@ from hindsight_api.extensions import (
     RecallResult,
     ReflectContext,
     ReflectResultContext,
+    RefreshMentalModelContext,
+    RefreshMentalModelResult,
     RequestContext,
     RetainContext,
     RetainResult,
@@ -24,9 +26,6 @@ from hindsight_api.extensions import (
     TenantExtension,
     ValidationResult,
     load_extension,
-    # Consolidation operation
-    ConsolidateContext,
-    ConsolidateResult,
 )
 
 
@@ -96,6 +95,7 @@ class RateLimitingValidator(OperationValidatorExtension):
         self.retain_counts: dict[str, int] = defaultdict(int)
         self.recall_counts: dict[str, int] = defaultdict(int)
         self.reflect_counts: dict[str, int] = defaultdict(int)
+        self.refresh_mental_model_counts: dict[str, int] = defaultdict(int)
 
     async def validate_retain(self, ctx: RetainContext) -> ValidationResult:
         self.retain_counts[ctx.bank_id] += 1
@@ -121,6 +121,16 @@ class RateLimitingValidator(OperationValidatorExtension):
             )
         return ValidationResult.accept()
 
+    async def validate_refresh_mental_model(
+        self, ctx: RefreshMentalModelContext
+    ) -> ValidationResult:
+        self.refresh_mental_model_counts[ctx.bank_id] += 1
+        if self.refresh_mental_model_counts[ctx.bank_id] > self.max_attempts:
+            return ValidationResult.reject(
+                f"Refresh mental model limit exceeded for bank {ctx.bank_id}"
+            )
+        return ValidationResult.accept()
+
 
 class TrackingValidator(OperationValidatorExtension):
     """
@@ -131,18 +141,16 @@ class TrackingValidator(OperationValidatorExtension):
 
     def __init__(self, config: dict):
         super().__init__(config)
-        # Pre-hook tracking - Core operations
+        # Pre-hook tracking
         self.pre_retain_calls: list[RetainContext] = []
         self.pre_recall_calls: list[RecallContext] = []
         self.pre_reflect_calls: list[ReflectContext] = []
-        # Post-hook tracking - Core operations
+        self.pre_refresh_mental_model_calls: list[RefreshMentalModelContext] = []
+        # Post-hook tracking
         self.post_retain_calls: list[RetainResult] = []
         self.post_recall_calls: list[RecallResult] = []
         self.post_reflect_calls: list[ReflectResultContext] = []
-        # Pre-hook tracking - Consolidation
-        self.pre_consolidate_calls: list[ConsolidateContext] = []
-        # Post-hook tracking - Consolidation
-        self.post_consolidate_calls: list[ConsolidateResult] = []
+        self.post_refresh_mental_model_calls: list[RefreshMentalModelResult] = []
 
     async def validate_retain(self, ctx: RetainContext) -> ValidationResult:
         self.pre_retain_calls.append(ctx)
@@ -156,6 +164,12 @@ class TrackingValidator(OperationValidatorExtension):
         self.pre_reflect_calls.append(ctx)
         return ValidationResult.accept()
 
+    async def validate_refresh_mental_model(
+        self, ctx: RefreshMentalModelContext
+    ) -> ValidationResult:
+        self.pre_refresh_mental_model_calls.append(ctx)
+        return ValidationResult.accept()
+
     async def on_retain_complete(self, result: RetainResult) -> None:
         self.post_retain_calls.append(result)
 
@@ -165,13 +179,10 @@ class TrackingValidator(OperationValidatorExtension):
     async def on_reflect_complete(self, result: ReflectResultContext) -> None:
         self.post_reflect_calls.append(result)
 
-    # Consolidation hooks
-    async def validate_consolidate(self, ctx: ConsolidateContext) -> ValidationResult:
-        self.pre_consolidate_calls.append(ctx)
-        return ValidationResult.accept()
-
-    async def on_consolidate_complete(self, result: ConsolidateResult) -> None:
-        self.post_consolidate_calls.append(result)
+    async def on_refresh_mental_model_complete(
+        self, result: RefreshMentalModelResult
+    ) -> None:
+        self.post_refresh_mental_model_calls.append(result)
 
 
 class TestMemoryEngineValidation:
@@ -530,6 +541,105 @@ class TestOperationHooksParameters:
         assert len(validator.pre_recall_calls) == 1
         assert len(validator.post_recall_calls) == 1
 
+    @pytest.mark.asyncio
+    async def test_refresh_mental_model_pre_hook_receives_all_parameters(
+        self, memory_with_tracking_validator
+    ):
+        """Pre-refresh-mental-model hook receives all user-provided parameters."""
+        import uuid
+
+        memory, validator = memory_with_tracking_validator
+        bank_id = f"test-refresh-mm-params-{uuid.uuid4().hex[:8]}"
+        ctx = RequestContext(api_key="test-key")
+
+        # Create bank first (get_bank_profile auto-creates if needed)
+        await memory.get_bank_profile(bank_id, request_context=ctx)
+
+        # Create a pinned mental model
+        model = await memory.create_mental_model(
+            bank_id=bank_id,
+            name="Test Model",
+            description="Test description",
+            subtype="pinned",
+            request_context=ctx,
+        )
+
+        assert model is not None
+        model_id = model["id"]
+
+        # Attempt to refresh (may not actually refresh if no data, but hook should be called)
+        try:
+            await memory.refresh_mental_model(
+                bank_id=bank_id,
+                model_id=model_id,
+                request_context=ctx,
+            )
+        except Exception:
+            pass  # May fail if no data
+
+        # Check pre-hook was called
+        assert len(validator.pre_refresh_mental_model_calls) == 1
+        pre_ctx = validator.pre_refresh_mental_model_calls[0]
+        assert pre_ctx.bank_id == bank_id
+        assert pre_ctx.model_id == model_id
+        assert pre_ctx.request_context == ctx
+
+    @pytest.mark.asyncio
+    async def test_refresh_mental_model_post_hook_receives_token_usage(
+        self, memory_with_tracking_validator
+    ):
+        """Post-refresh-mental-model hook receives token usage information."""
+        import uuid
+
+        memory, validator = memory_with_tracking_validator
+        bank_id = f"test-refresh-mm-tokens-{uuid.uuid4().hex[:8]}"
+        ctx = RequestContext(api_key="test-key")
+
+        # Store some content first
+        await memory.retain_batch_async(
+            bank_id=bank_id,
+            contents=[
+                {"content": "Alice is a software engineer who works on machine learning."},
+                {"content": "Alice enjoys hiking and outdoor activities on weekends."},
+                {"content": "Alice has been working at the company for 5 years."},
+            ],
+            request_context=ctx,
+        )
+
+        # Create a pinned mental model
+        model = await memory.create_mental_model(
+            bank_id=bank_id,
+            name="Alice Profile",
+            description="Profile of Alice including work and hobbies",
+            subtype="pinned",
+            request_context=ctx,
+        )
+
+        if model:
+            model_id = model["id"]
+
+            # Refresh the mental model
+            result = await memory.refresh_mental_model(
+                bank_id=bank_id,
+                model_id=model_id,
+                request_context=ctx,
+            )
+
+            # Check post-hook was called with token usage
+            if validator.post_refresh_mental_model_calls:
+                post_result = validator.post_refresh_mental_model_calls[0]
+                assert post_result.bank_id == bank_id
+                assert post_result.model_id == model_id
+                assert post_result.request_context == ctx
+                assert post_result.success is True
+                assert post_result.error is None
+
+                # Token usage should be populated (may be 0 if refresh was skipped)
+                assert post_result.total_tokens >= 0
+                assert post_result.input_tokens >= 0
+                assert post_result.output_tokens >= 0
+                assert post_result.duration_ms >= 0
+
 
 class TestTenantExtension:
     """Tests for TenantExtension and ApiKeyTenantExtension."""

hindsight-api/tests/test_http_api_integration.py

@@ -969,22 +969,24 @@ async def test_reflect_returns_token_usage(api_client):
     assert "text" in result
     assert len(result["text"]) > 0
 
-    # Verify usage field exists and is populated (agentic reflect aggregates all LLM calls)
+    # Verify usage field exists (may be None for agentic reflect which makes multiple LLM calls)
     assert "usage" in result, "Response should include 'usage' field"
     usage = result["usage"]
 
-    # Usage must be present - agentic reflect now aggregates token usage from all LLM calls
-    assert usage is not None, "Usage should not be None - reflect aggregates all LLM call usages"
-    assert "input_tokens" in usage, "Usage should have 'input_tokens'"
-    assert "output_tokens" in usage, "Usage should have 'output_tokens'"
-    assert "total_tokens" in usage, "Usage should have 'total_tokens'"
+    # Usage is optional - agentic reflect doesn't aggregate multiple LLM call usages
+    if usage is not None:
+        assert "input_tokens" in usage, "Usage should have 'input_tokens'"
+        assert "output_tokens" in usage, "Usage should have 'output_tokens'"
+        assert "total_tokens" in usage, "Usage should have 'total_tokens'"
 
-    # Verify token counts are valid
-    assert usage["input_tokens"] > 0, f"Expected input_tokens > 0, got {usage['input_tokens']}"
-    assert usage["output_tokens"] >= 0, f"Expected output_tokens >= 0, got {usage['output_tokens']}"
-    assert usage["total_tokens"] == usage["input_tokens"] + usage["output_tokens"]
+        # Verify token counts are valid
+        assert usage["input_tokens"] > 0, f"Expected input_tokens > 0, got {usage['input_tokens']}"
+        assert usage["output_tokens"] >= 0, f"Expected output_tokens >= 0, got {usage['output_tokens']}"
+        assert usage["total_tokens"] == usage["input_tokens"] + usage["output_tokens"]
 
-    print(f"Reflect token usage: input={usage['input_tokens']}, output={usage['output_tokens']}, total={usage['total_tokens']}")
+        print(f"Reflect token usage: input={usage['input_tokens']}, output={usage['output_tokens']}, total={usage['total_tokens']}")
+    else:
+        print("Reflect usage is None (expected for agentic reflect)")
 
 
 @pytest.mark.asyncio

hindsight-api/tests/test_link_expansion_retrieval.py

@@ -1,278 +0,0 @@
-"""
-Tests for LinkExpansion graph retrieval.
-
-Tests cover the entity-based graph traversal for observations.
-"""
-
-from datetime import datetime, timezone
-
-import pytest
-
-
-@pytest.fixture(autouse=True)
-def enable_observations():
-    """Enable observations for all tests in this module."""
-    from hindsight_api.config import get_config
-
-    config = get_config()
-    original_value = config.enable_observations
-    config.enable_observations = True
-    yield
-    config.enable_observations = original_value
-
-
-@pytest.mark.asyncio
-async def test_link_expansion_observation_graph_retrieval(memory, request_context):
-    """
-    Test that observations can find other observations via shared entities.
-
-    This tests the scenario where:
-    1. World fact A has entity "Python"
-    2. World fact B has entity "Python"
-    3. Observation OA is derived from world fact A
-    4. Observation OB is derived from world fact B
-
-    When searching for observations related to OA, graph retrieval should find OB
-    because they share the "Python" entity through their source world facts.
-
-    Current issue: Graph retrieval returns 0 for observations because:
-    - Entity links are copied from world facts to observations during consolidation
-    - But the entity expansion query filters by fact_type
-    - Observations only share entities with world facts (cross-type), not with other observations
-    - So filtering to fact_type='observation' returns 0 results
-    """
-    bank_id = f"test_link_expansion_obs_{datetime.now(timezone.utc).timestamp()}"
-
-    try:
-        # Store world facts with shared entities using retain_batch_async
-        # We need enough facts that semantic search won't return all of them as seeds
-        # Key: "Alice" query should find Alice's observation but NOT Bob's via semantic search
-        # Then graph retrieval should find Bob via shared "Python" entity
-        await memory.retain_batch_async(
-            bank_id=bank_id,
-            contents=[
-                # Python developers - should be connected via "Python" entity
-                {
-                    "content": "Alice works with Python at TechCorp building REST APIs",
-                    "context": "employee info",
-                    "entities": [{"text": "Python"}, {"text": "Alice"}, {"text": "TechCorp"}],
-                },
-                {
-                    "content": "Bob uses Python at DataSoft for machine learning models",
-                    "context": "employee info",
-                    "entities": [{"text": "Python"}, {"text": "Bob"}, {"text": "DataSoft"}],
-                },
-                # Many unrelated facts to dilute semantic search and ensure
-                # "Alice" query only finds Alice-related content as seeds
-                {
-                    "content": "The weather in San Francisco is often foggy and cool",
-                    "context": "weather info",
-                    "entities": [{"text": "San Francisco"}],
-                },
-                {
-                    "content": "Tokyo is the capital city of Japan with many trains",
-                    "context": "geography info",
-                    "entities": [{"text": "Tokyo"}, {"text": "Japan"}],
-                },
-                {
-                    "content": "The Great Wall of China is a historic fortification",
-                    "context": "history info",
-                    "entities": [{"text": "Great Wall"}, {"text": "China"}],
-                },
-                {
-                    "content": "Coffee beans are grown in tropical regions worldwide",
-                    "context": "food info",
-                    "entities": [{"text": "Coffee"}],
-                },
-                {
-                    "content": "Electric vehicles are becoming more popular globally",
-                    "context": "technology info",
-                    "entities": [{"text": "Electric vehicles"}],
-                },
-                {
-                    "content": "The Amazon rainforest contains diverse wildlife species",
-                    "context": "nature info",
-                    "entities": [{"text": "Amazon"}, {"text": "Rainforest"}],
-                },
-                {
-                    "content": "Basketball is a popular sport in the United States",
-                    "context": "sports info",
-                    "entities": [{"text": "Basketball"}, {"text": "United States"}],
-                },
-                {
-                    "content": "Mozart composed many famous classical music pieces",
-                    "context": "music info",
-                    "entities": [{"text": "Mozart"}, {"text": "Classical music"}],
-                },
-            ],
-            request_context=request_context,
-        )
-
-        # Consolidation runs automatically after retain - wait for it to complete
-        # by querying for observations (consolidation creates them)
-        import asyncio
-        from hindsight_api.engine.memory_engine import Budget
-
-        # Wait for consolidation to complete with retry logic
-        # Consolidation runs as a background task and may take longer in CI
-        obs_result = None
-        for _ in range(30):  # Try up to 30 times (30 seconds max)
-            await asyncio.sleep(1)  # Wait 1 second between attempts
-            obs_result = await memory.recall_async(
-                bank_id=bank_id,
-                query="Python developer",
-                fact_type=["observation"],
-                budget=Budget.MID,
-                max_tokens=2048,
-                request_context=request_context,
-            )
-            if obs_result.results and len(obs_result.results) >= 1:
-                break
-
-        assert obs_result is not None and obs_result.results is not None, "Should have observations after consolidation"
-        # We should have observations from consolidation
-        assert len(obs_result.results) >= 1, f"Should have at least 1 observation about Python, got {len(obs_result.results)}"
-
-        # Now test graph retrieval specifically
-        # Query for Alice - should find Bob via shared "Python" entity
-        result = await memory.recall_async(
-            bank_id=bank_id,
-            query="Alice",
-            fact_type=["observation"],
-            budget=Budget.MID,
-            max_tokens=2048,
-            enable_trace=True,
-            request_context=request_context,
-        )
-
-        # Verify graph retrieval is working by checking the internal debug logs
-        # The graph retrieval finds observations via entity links, but may not return
-        # NEW results if semantic search already found all connected observations.
-        # This is correct behavior - we verify the entity traversal path works.
-
-        # Check the trace for graph results
-        assert result.trace is not None, "Should have trace data"
-
-        # The key verification: the entity expansion path works (sources -> entities -> observations)
-        # We validated this in the debug logs above:
-        # - Observations have source_memory_ids pointing to world facts ✓
-        # - World facts have entity links ✓
-        # - Graph retrieval can traverse this path (seen in logs: potential_obs > 0)
-
-        # For a more rigorous test, we need data where semantic search misses something.
-        # Let's verify the world fact graph retrieval works (it uses direct entity links).
-        world_result = await memory.recall_async(
-            bank_id=bank_id,
-            query="Alice",
-            fact_type=["world"],
-            budget=Budget.MID,
-            max_tokens=2048,
-            enable_trace=True,
-            request_context=request_context,
-        )
-
-        assert world_result.trace is not None, "Should have trace data for world facts"
-        world_retrieval_results = world_result.trace.get("retrieval_results", [])
-        world_graph_results = [
-            r for r in world_retrieval_results if r.get("method_name") == "graph"
-        ]
-
-        if world_graph_results:
-            world_graph_result = [r for r in world_graph_results if r.get("fact_type") == "world"][0]
-            world_graph_results_list = world_graph_result.get("results", [])
-
-            # World facts use direct entity links, so graph may find results
-            if world_graph_results_list:
-                print(f"\n✓ Graph retrieval found {len(world_graph_results_list)} connected world facts")
-                graph_texts = [r.get("text", "") for r in world_graph_results_list]
-                bob_found = any("Bob" in t or "DataSoft" in t for t in graph_texts)
-                if bob_found:
-                    print("  Found Bob's world fact via shared 'Python' entity!")
-
-        print("\n✓ Link expansion observation test passed!")
-        print("  Entity traversal path verified (observations -> sources -> entities -> connected sources -> observations)")
-
-    finally:
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-
-@pytest.mark.asyncio
-async def test_link_expansion_world_fact_graph_retrieval(memory, request_context):
-    """
-    Test that world facts can find other world facts via shared entities.
-
-    This verifies the direct entity link traversal for world facts works correctly.
-    Note: When semantic search finds all world facts as seeds, graph retrieval
-    won't return NEW results (this is correct - it shouldn't duplicate results).
-    """
-    bank_id = f"test_link_expansion_world_{datetime.now(timezone.utc).timestamp()}"
-
-    try:
-        # Store world facts with shared entities
-        await memory.retain_batch_async(
-            bank_id=bank_id,
-            contents=[
-                # Python developers - should be connected via "Python" entity
-                {
-                    "content": "Alice works with Python at TechCorp building REST APIs",
-                    "context": "employee info",
-                    "entities": [{"text": "Python"}, {"text": "Alice"}, {"text": "TechCorp"}],
-                },
-                {
-                    "content": "Bob uses Python at DataSoft for machine learning models",
-                    "context": "employee info",
-                    "entities": [{"text": "Python"}, {"text": "Bob"}, {"text": "DataSoft"}],
-                },
-                # Unrelated facts
-                {
-                    "content": "The weather in San Francisco is often foggy",
-                    "context": "weather info",
-                    "entities": [{"text": "San Francisco"}],
-                },
-                {
-                    "content": "Coffee beans are grown in tropical regions",
-                    "context": "food info",
-                    "entities": [{"text": "Coffee"}],
-                },
-            ],
-            request_context=request_context,
-        )
-
-        from hindsight_api.engine.memory_engine import Budget
-
-        # Query for Alice
-        result = await memory.recall_async(
-            bank_id=bank_id,
-            query="Alice",
-            fact_type=["world"],
-            budget=Budget.MID,
-            max_tokens=2048,
-            enable_trace=True,
-            request_context=request_context,
-        )
-
-        assert result.trace is not None, "Should have trace data"
-
-        # Verify graph retrieval ran (it may or may not find new results depending
-        # on whether semantic search already found everything)
-        retrieval_results = result.trace.get("retrieval_results", [])
-        graph_results = [
-            r for r in retrieval_results if r.get("method_name") == "graph"
-        ]
-        assert len(graph_results) > 0, "Should have graph retrieval results in trace"
-
-        # The important thing is that recall works and returns relevant results
-        assert result.results is not None and len(result.results) > 0, (
-            "Should return results for 'Alice' query"
-        )
-
-        # Alice's result should be at or near the top
-        result_texts = [r.text for r in result.results]
-        alice_found = any("Alice" in t for t in result_texts)
-        assert alice_found, f"Should find Alice in results: {result_texts[:3]}"
-
-        print("\n✓ Link expansion world fact test passed!")
-        print(f"  Recall returned {len(result.results)} results for 'Alice' query")
-
-    finally:
-        await memory.delete_bank(bank_id, request_context=request_context)

hindsight-api/tests/test_llm_tools.py

@@ -241,27 +241,24 @@ class TestReflectToolSchemas:
         tools = get_reflect_tools()
 
         tool_names = [t["function"]["name"] for t in tools]
-        assert "search_mental_models" in tool_names
-        assert "search_observations" in tool_names
+        assert "list_mental_models" in tool_names
+        assert "get_mental_model" in tool_names
         assert "recall" in tool_names
+        assert "learn" in tool_names
         assert "expand" in tool_names
         assert "done" in tool_names
 
-    def test_get_reflect_tools_with_directives(self):
-        """Test getting reflect tools with directive rules."""
+    def test_get_reflect_tools_without_learn(self):
+        """Test getting reflect tools without learn."""
         from hindsight_api.engine.reflect.tools_schema import get_reflect_tools
 
-        tools = get_reflect_tools(directive_rules=["Always respond in French"])
+        tools = get_reflect_tools(enable_learn=False)
 
         tool_names = [t["function"]["name"] for t in tools]
+        assert "learn" not in tool_names
         assert "recall" in tool_names
         assert "done" in tool_names
 
-        # Done tool should have directive_compliance field when directives are present
-        done_tool = next(t for t in tools if t["function"]["name"] == "done")
-        params = done_tool["function"]["parameters"]["properties"]
-        assert "directive_compliance" in params
-
     def test_get_reflect_tools_answer_mode(self):
         """Test getting reflect tools with answer output mode."""
         from hindsight_api.engine.reflect.tools_schema import get_reflect_tools
@@ -273,8 +270,7 @@ class TestReflectToolSchemas:
 
         assert "answer" in params
         assert "memory_ids" in params
-        assert "observation_ids" in params
-        assert "mental_model_ids" in params
+        assert "model_ids" in params
 
 
 class TestLLMToolCallResult:

hindsight-api/tests/test_main_module.py

@@ -355,14 +355,15 @@ class TestMainModuleExtensionLoading:
 
 # Mock extensions for testing
 from hindsight_api.extensions import (
+    TenantExtension,
+    TenantContext,
+    RequestContext,
     OperationValidatorExtension,
+    ValidationResult,
+    RetainContext,
     RecallContext,
     ReflectContext,
-    RequestContext,
-    RetainContext,
-    TenantContext,
-    TenantExtension,
-    ValidationResult,
+    RefreshMentalModelContext,
 )
 
 
@@ -376,11 +377,6 @@ class MockTenantExtension(TenantExtension):
     async def authenticate(self, request_context: RequestContext) -> TenantContext:
         return TenantContext(schema_name="public")
 
-    async def list_tenants(self) -> list:
-        from hindsight_api.extensions.tenant import Tenant
-
-        return [Tenant(schema="public")]
-
     def set_context(self, context) -> None:
         self._context_set = True
 
@@ -399,3 +395,6 @@ class MockOperationValidator(OperationValidatorExtension):
 
     async def validate_reflect(self, ctx: ReflectContext) -> ValidationResult:
         return ValidationResult.accept()
+
+    async def validate_refresh_mental_model(self, ctx: RefreshMentalModelContext) -> ValidationResult:
+        return ValidationResult.accept()

hindsight-api/tests/test_mcp_local.py

@@ -62,9 +62,9 @@ async def test_local_mcp_server_recall(mock_memory):
     tools = mcp_server._tool_manager._tools
     assert "recall" in tools
 
-    # Call recall
+    # Call recall with new params
     recall_tool = tools["recall"]
-    result = await recall_tool.fn(query="test query", max_tokens=2048)
+    result = await recall_tool.fn(query="test query", max_tokens=2048, budget="mid")
 
     # Result is a dict
     assert isinstance(result, dict)
@@ -75,7 +75,7 @@ async def test_local_mcp_server_recall(mock_memory):
     assert call_kwargs["bank_id"] == "test-bank"
     assert call_kwargs["query"] == "test query"
     assert call_kwargs["max_tokens"] == 2048
-    assert call_kwargs["budget"] == Budget.HIGH
+    assert call_kwargs["budget"] == Budget.MID
 
 
 @pytest.mark.asyncio
@@ -141,7 +141,7 @@ async def test_local_mcp_server_recall_error_handling(mock_memory):
 
 @pytest.mark.asyncio
 async def test_local_mcp_server_recall_with_defaults(mock_memory):
-    """Test that recall uses default max_tokens and HIGH budget."""
+    """Test that recall uses default max_tokens and budget."""
     from hindsight_api.mcp_local import create_local_mcp_server
     from hindsight_api.engine.memory_engine import Budget
 
@@ -159,54 +159,4 @@ async def test_local_mcp_server_recall_with_defaults(mock_memory):
 
     call_kwargs = mock_memory.recall_async.call_args.kwargs
     assert call_kwargs["max_tokens"] == 4096
-    assert call_kwargs["budget"] == Budget.HIGH
-
-
-@pytest.mark.asyncio
-async def test_local_mcp_server_retain_with_timestamp(mock_memory):
-    """Test that retain passes timestamp as event_date."""
-    from datetime import datetime, timezone
-    from hindsight_api.mcp_local import create_local_mcp_server
-
-    mcp_server = create_local_mcp_server("test-bank", memory=mock_memory)
-
-    tools = mcp_server._tool_manager._tools
-    retain_tool = tools["retain"]
-
-    # Call retain with timestamp
-    result = await retain_tool.fn(
-        content="test content", context="test_context", timestamp="2024-01-15T10:30:00Z"
-    )
-
-    assert result["status"] == "accepted"
-
-    # Wait for background task
-    await asyncio.sleep(0.1)
-
-    call_kwargs = mock_memory.retain_batch_async.call_args.kwargs
-    contents = call_kwargs["contents"]
-    assert len(contents) == 1
-    assert contents[0]["content"] == "test content"
-    assert contents[0]["context"] == "test_context"
-    assert "event_date" in contents[0]
-    assert contents[0]["event_date"] == datetime(2024, 1, 15, 10, 30, 0, tzinfo=timezone.utc)
-
-
-@pytest.mark.asyncio
-async def test_local_mcp_server_retain_with_invalid_timestamp(mock_memory):
-    """Test that retain rejects invalid timestamp format."""
-    from hindsight_api.mcp_local import create_local_mcp_server
-
-    mcp_server = create_local_mcp_server("test-bank", memory=mock_memory)
-
-    tools = mcp_server._tool_manager._tools
-    retain_tool = tools["retain"]
-
-    # Call retain with invalid timestamp
-    result = await retain_tool.fn(content="test content", timestamp="not-a-date")
-
-    assert result["status"] == "error"
-    assert "Invalid timestamp format" in result["message"]
-
-    # Verify retain_batch_async was NOT called
-    mock_memory.retain_batch_async.assert_not_called()
+    assert call_kwargs["budget"] == Budget.LOW

hindsight-api/tests/test_mcp_tools.py

@@ -1,63 +0,0 @@
-"""Tests for the shared MCP tools module."""
-
-from datetime import datetime, timezone
-
-import pytest
-
-from hindsight_api.mcp_tools import build_content_dict, parse_timestamp
-
-
-class TestParseTimestamp:
-    """Tests for parse_timestamp function."""
-
-    def test_parse_iso_format_with_z(self):
-        """Test parsing ISO format with Z suffix."""
-        result = parse_timestamp("2024-01-15T10:30:00Z")
-        assert result == datetime(2024, 1, 15, 10, 30, 0, tzinfo=timezone.utc)
-
-    def test_parse_iso_format_with_offset(self):
-        """Test parsing ISO format with timezone offset."""
-        result = parse_timestamp("2024-01-15T10:30:00+00:00")
-        assert result == datetime(2024, 1, 15, 10, 30, 0, tzinfo=timezone.utc)
-
-    def test_parse_iso_format_without_tz(self):
-        """Test parsing ISO format without timezone."""
-        result = parse_timestamp("2024-01-15T10:30:00")
-        assert result == datetime(2024, 1, 15, 10, 30, 0)
-
-    def test_parse_invalid_format_raises(self):
-        """Test that invalid format raises ValueError."""
-        with pytest.raises(ValueError) as exc_info:
-            parse_timestamp("not-a-date")
-        assert "Invalid timestamp format" in str(exc_info.value)
-
-
-class TestBuildContentDict:
-    """Tests for build_content_dict function."""
-
-    def test_basic_content(self):
-        """Test building content dict with just content and context."""
-        result, error = build_content_dict("test content", "test_context")
-        assert error is None
-        assert result == {"content": "test content", "context": "test_context"}
-
-    def test_with_valid_timestamp(self):
-        """Test building content dict with valid timestamp."""
-        result, error = build_content_dict("test content", "test_context", "2024-01-15T10:30:00Z")
-        assert error is None
-        assert result["content"] == "test content"
-        assert result["context"] == "test_context"
-        assert result["event_date"] == datetime(2024, 1, 15, 10, 30, 0, tzinfo=timezone.utc)
-
-    def test_with_invalid_timestamp(self):
-        """Test building content dict with invalid timestamp."""
-        result, error = build_content_dict("test content", "test_context", "invalid")
-        assert error is not None
-        assert "Invalid timestamp format" in error
-        assert result == {}
-
-    def test_with_none_timestamp(self):
-        """Test building content dict with None timestamp."""
-        result, error = build_content_dict("test content", "test_context", None)
-        assert error is None
-        assert "event_date" not in result

hindsight-api/tests/test_multilingual.py

@@ -275,165 +275,6 @@ async def test_retain_japanese_content(memory, request_context):
                 pass
 
 
-@pytest.mark.asyncio
-async def test_english_content_stays_english(memory, request_context):
-    """
-    Test that English content is NOT incorrectly translated to Japanese or Chinese.
-
-    This test specifically catches the bug where the language instruction in the
-    CONCISE extraction prompt mentioned Japanese/Chinese explicitly, which primed
-    the LLM to sometimes output facts in those languages even for English input.
-
-    See: https://github.com/vectorize-io/hindsight/issues/181
-    """
-    bank_id = f"test_english_retain_{datetime.now(timezone.utc).timestamp()}"
-
-    try:
-        # English content about a developer
-        english_content = """
-        John Smith is a software engineer at TechCorp in Seattle.
-        He specializes in machine learning and has been working on
-        recommendation systems for the past three years.
-        Last month, he launched a new feature that improved click-through rates by 25%.
-        He prefers working in Python and uses PyTorch for model training.
-        """
-
-        unit_ids = await memory.retain_async(
-            bank_id=bank_id,
-            content=english_content,
-            context="Team profile",
-            event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
-            request_context=request_context,
-        )
-
-        logger.info(f"Retained {len(unit_ids)} facts from English content")
-        assert len(unit_ids) > 0, "Should have extracted facts from English content"
-
-        # Recall with English query
-        result = await memory.recall_async(
-            bank_id=bank_id,
-            query="Tell me about John Smith",
-            budget=Budget.MID,
-            max_tokens=1000,
-            fact_type=["world"],
-            request_context=request_context,
-        )
-
-        assert len(result.results) > 0, "Should recall facts about John Smith"
-
-        # Verify facts are NOT in Japanese or Chinese
-        for fact in result.results:
-            logger.info(f"Fact: {fact.text}")
-
-            # Count Japanese characters (hiragana, katakana)
-            japanese_chars = sum(
-                1 for char in fact.text
-                if ("\u3040" <= char <= "\u309f") or ("\u30a0" <= char <= "\u30ff")
-            )
-
-            # Count Chinese/CJK characters (excluding those also used in Japanese)
-            # Note: Kanji/CJK ideographs overlap between Chinese and Japanese
-            cjk_chars = sum(1 for char in fact.text if "\u4e00" <= char <= "\u9fff")
-
-            # For English input, there should be minimal CJK characters
-            # Allow for occasional edge cases (e.g., proper nouns) but not full translation
-            total_chars = len(fact.text)
-            cjk_ratio = cjk_chars / max(total_chars, 1)
-
-            assert cjk_ratio < 0.1, (
-                f"English content was incorrectly translated to CJK language! "
-                f"CJK ratio: {cjk_ratio:.1%}, Japanese chars: {japanese_chars}, CJK chars: {cjk_chars}. "
-                f"Fact: {fact.text}"
-            )
-
-        logger.info("English content test passed - facts stayed in English")
-
-    finally:
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-
-@pytest.mark.asyncio
-async def test_italian_content_stays_italian(memory, request_context):
-    """
-    Test that Italian content is NOT incorrectly translated to Japanese or Chinese.
-
-    Similar to the English test, this catches the bug where non-CJK languages
-    could be incorrectly translated due to biased language instruction.
-
-    See: https://github.com/vectorize-io/hindsight/issues/181
-    """
-    bank_id = f"test_italian_retain_{datetime.now(timezone.utc).timestamp()}"
-
-    try:
-        # Italian content about a chef
-        italian_content = """
-        Marco Rossi è uno chef italiano che lavora in un ristorante a Milano.
-        È specializzato nella cucina toscana e ha vinto tre premi gastronomici.
-        Il mese scorso ha aperto un nuovo ristorante nel centro della città.
-        Preferisce usare ingredienti freschi e locali per i suoi piatti.
-        """
-
-        unit_ids = await memory.retain_async(
-            bank_id=bank_id,
-            content=italian_content,
-            context="Profilo dello chef",
-            event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
-            request_context=request_context,
-        )
-
-        logger.info(f"Retained {len(unit_ids)} facts from Italian content")
-        assert len(unit_ids) > 0, "Should have extracted facts from Italian content"
-
-        # Recall with Italian query
-        result = await memory.recall_async(
-            bank_id=bank_id,
-            query="Dimmi di Marco Rossi",  # "Tell me about Marco Rossi"
-            budget=Budget.MID,
-            max_tokens=1000,
-            fact_type=["world"],
-            request_context=request_context,
-        )
-
-        assert len(result.results) > 0, "Should recall facts about Marco Rossi"
-
-        # Verify facts are NOT in Japanese or Chinese - should stay in Italian
-        for fact in result.results:
-            logger.info(f"Fact: {fact.text}")
-
-            # Count CJK characters
-            cjk_chars = sum(1 for char in fact.text if "\u4e00" <= char <= "\u9fff")
-            japanese_chars = sum(
-                1 for char in fact.text
-                if ("\u3040" <= char <= "\u309f") or ("\u30a0" <= char <= "\u30ff")
-            )
-
-            total_chars = len(fact.text)
-            cjk_ratio = (cjk_chars + japanese_chars) / max(total_chars, 1)
-
-            assert cjk_ratio < 0.1, (
-                f"Italian content was incorrectly translated to CJK language! "
-                f"CJK ratio: {cjk_ratio:.1%}. Fact: {fact.text}"
-            )
-
-        # Verify facts contain Italian words (basic sanity check)
-        all_text = " ".join(f.text for f in result.results).lower()
-        italian_indicators = ["marco", "rossi", "chef", "ristorante", "milano", "cucina", "italiano", "italiana"]
-        has_italian = any(word in all_text for word in italian_indicators)
-
-        # Allow English translation as acceptable (not ideal but not the bug)
-        english_indicators = ["chef", "restaurant", "milan", "italian", "cooking"]
-        has_english = any(word in all_text for word in english_indicators)
-
-        assert has_italian or has_english, (
-            f"Expected facts to be in Italian or English, but got neither. Facts: {all_text}"
-        )
-
-        logger.info("Italian content test passed - facts not translated to CJK")
-
-    finally:
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-
 @pytest.mark.asyncio
 async def test_mixed_language_entities(memory, request_context):
     """

hindsight-api/tests/test_observation_trends.py

@@ -0,0 +1,405 @@
+"""Tests for observation trend computation and evidence-grounded models."""
+
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from hindsight_api.engine.reflect.observations import (
+    CandidateObservation,
+    Observation,
+    ObservationEvidence,
+    Trend,
+    compute_trend,
+    verify_evidence_quotes,
+)
+
+
+class TestComputeTrend:
+    """Tests for the compute_trend function."""
+
+    def test_empty_evidence_returns_stale(self):
+        """No evidence should return STALE trend."""
+        trend = compute_trend([])
+        assert trend == Trend.STALE
+
+    def test_all_recent_evidence_returns_new(self):
+        """All evidence within recent window (30 days) should return NEW trend.
+
+        Scenario: User just started using the app and mentioned they like coffee twice.
+        Both mentions are within the last 2 weeks, so this is a NEW observation.
+        """
+        now = datetime.now(timezone.utc)
+        evidence = [
+            ObservationEvidence(
+                memory_id="mem-coffee-morning",
+                quote="I always start my day with a large black coffee",
+                relevance="Shows preference for coffee and morning routine",
+                timestamp=now - timedelta(days=5),
+            ),
+            ObservationEvidence(
+                memory_id="mem-coffee-meeting",
+                quote="grabbed coffee before the standup meeting",
+                relevance="Confirms regular coffee consumption",
+                timestamp=now - timedelta(days=10),
+            ),
+        ]
+
+        trend = compute_trend(evidence, now=now)
+        assert trend == Trend.NEW
+
+    def test_no_recent_evidence_returns_stale(self):
+        """No evidence in recent window should return STALE trend.
+
+        Scenario: User mentioned running 3 months ago but hasn't mentioned it since.
+        The observation about running as a hobby may no longer be accurate.
+        """
+        now = datetime.now(timezone.utc)
+        evidence = [
+            ObservationEvidence(
+                memory_id="mem-running-march",
+                quote="training for a half marathon in the spring",
+                relevance="Shows interest in running",
+                timestamp=now - timedelta(days=60),
+            ),
+            ObservationEvidence(
+                memory_id="mem-running-feb",
+                quote="went for a 10k run this morning",
+                relevance="Active runner",
+                timestamp=now - timedelta(days=100),
+            ),
+        ]
+
+        trend = compute_trend(evidence, now=now)
+        assert trend == Trend.STALE
+
+    def test_stable_evidence_distribution(self):
+        """Evidence spread evenly across time should return STABLE trend.
+
+        Scenario: User has consistently mentioned working remotely over 4 months.
+        Evidence is well-distributed, indicating a stable, ongoing preference.
+        """
+        now = datetime.now(timezone.utc)
+        evidence = [
+            # Recent (within 30 days)
+            ObservationEvidence(
+                memory_id="mem-remote-jan",
+                quote="working from my home office today",
+                relevance="Current remote work",
+                timestamp=now - timedelta(days=5),
+            ),
+            ObservationEvidence(
+                memory_id="mem-remote-dec",
+                quote="the flexibility of remote work is great",
+                relevance="Values remote work",
+                timestamp=now - timedelta(days=15),
+            ),
+            # Middle period (30-90 days)
+            ObservationEvidence(
+                memory_id="mem-remote-nov",
+                quote="set up a standing desk at home",
+                relevance="Invested in home office",
+                timestamp=now - timedelta(days=45),
+            ),
+            ObservationEvidence(
+                memory_id="mem-remote-oct",
+                quote="prefer async communication over meetings",
+                relevance="Remote work style preference",
+                timestamp=now - timedelta(days=60),
+            ),
+            # Older (90+ days)
+            ObservationEvidence(
+                memory_id="mem-remote-sep",
+                quote="switched to fully remote last quarter",
+                relevance="Original transition to remote",
+                timestamp=now - timedelta(days=100),
+            ),
+            ObservationEvidence(
+                memory_id="mem-remote-aug",
+                quote="negotiated remote work in my new contract",
+                relevance="Intentional choice for remote",
+                timestamp=now - timedelta(days=120),
+            ),
+        ]
+
+        trend = compute_trend(evidence, now=now)
+        assert trend == Trend.STABLE
+
+    def test_strengthening_trend(self):
+        """Much more recent evidence than older should return STRENGTHENING trend.
+
+        Scenario: User has been increasingly talking about learning Python recently
+        after mentioning it once months ago. Interest appears to be growing.
+        """
+        now = datetime.now(timezone.utc)
+        evidence = [
+            # Lots of recent evidence - actively learning
+            ObservationEvidence(
+                memory_id="mem-python-project",
+                quote="finished my first Python project - a web scraper",
+                relevance="Completed Python project",
+                timestamp=now - timedelta(days=2),
+            ),
+            ObservationEvidence(
+                memory_id="mem-python-course",
+                quote="halfway through the Python bootcamp",
+                relevance="Active learning",
+                timestamp=now - timedelta(days=5),
+            ),
+            ObservationEvidence(
+                memory_id="mem-python-book",
+                quote="reading Fluent Python, it's excellent",
+                relevance="Deepening knowledge",
+                timestamp=now - timedelta(days=10),
+            ),
+            ObservationEvidence(
+                memory_id="mem-python-practice",
+                quote="solved 50 LeetCode problems in Python",
+                relevance="Practicing skills",
+                timestamp=now - timedelta(days=15),
+            ),
+            ObservationEvidence(
+                memory_id="mem-python-ide",
+                quote="set up VS Code with all the Python extensions",
+                relevance="Setting up environment",
+                timestamp=now - timedelta(days=20),
+            ),
+            # Only one old mention - initial interest
+            ObservationEvidence(
+                memory_id="mem-python-start",
+                quote="thinking about learning Python someday",
+                relevance="Initial interest",
+                timestamp=now - timedelta(days=100),
+            ),
+        ]
+
+        trend = compute_trend(evidence, now=now)
+        assert trend == Trend.STRENGTHENING
+
+    def test_weakening_trend(self):
+        """Much less recent evidence than older should return WEAKENING trend.
+
+        Scenario: User was very active in a book club last year but mentions
+        have tapered off. The observation about being a book club member
+        may be becoming less relevant.
+        """
+        now = datetime.now(timezone.utc)
+        evidence = [
+            # Only one recent mention
+            ObservationEvidence(
+                memory_id="mem-book-recent",
+                quote="haven't had time for book club lately",
+                relevance="Reduced participation",
+                timestamp=now - timedelta(days=10),
+            ),
+            # Lots of older evidence - was very active
+            ObservationEvidence(
+                memory_id="mem-book-aug",
+                quote="hosting book club at my place next week",
+                relevance="Active organizer",
+                timestamp=now - timedelta(days=40),
+            ),
+            ObservationEvidence(
+                memory_id="mem-book-july",
+                quote="leading the discussion on 1984",
+                relevance="Active participant",
+                timestamp=now - timedelta(days=50),
+            ),
+            ObservationEvidence(
+                memory_id="mem-book-june",
+                quote="we picked The Midnight Library for June",
+                relevance="Regular member",
+                timestamp=now - timedelta(days=60),
+            ),
+            ObservationEvidence(
+                memory_id="mem-book-may",
+                quote="book club was amazing tonight",
+                relevance="Enthusiastic member",
+                timestamp=now - timedelta(days=100),
+            ),
+            ObservationEvidence(
+                memory_id="mem-book-april",
+                quote="joined a new book club in my neighborhood",
+                relevance="Started participation",
+                timestamp=now - timedelta(days=110),
+            ),
+            ObservationEvidence(
+                memory_id="mem-book-march",
+                quote="excited to finally join a book club",
+                relevance="Initial enthusiasm",
+                timestamp=now - timedelta(days=120),
+            ),
+        ]
+
+        trend = compute_trend(evidence, now=now)
+        assert trend == Trend.WEAKENING
+
+
+class TestObservationModel:
+    """Tests for the Observation model."""
+
+    def test_observation_computed_trend(self):
+        """Observation should have computed trend property based on evidence."""
+        now = datetime.now(timezone.utc)
+        obs = Observation(
+            title="Morning meeting preference",
+            content="Prefers morning meetings over afternoon ones",
+            evidence=[
+                ObservationEvidence(
+                    memory_id="mem-morning-standup",
+                    quote="I'm most productive in morning meetings",
+                    relevance="Direct preference statement",
+                    timestamp=now - timedelta(days=5),
+                ),
+            ],
+            created_at=now,
+        )
+
+        assert obs.trend == Trend.NEW
+        assert obs.evidence_count == 1
+
+    def test_observation_evidence_span(self):
+        """Observation should compute evidence span correctly.
+
+        The span shows the date range of supporting evidence, helping
+        understand how long this pattern has been observed.
+        """
+        now = datetime.now(timezone.utc)
+        old_time = now - timedelta(days=100)
+        recent_time = now - timedelta(days=5)
+
+        obs = Observation(
+            title="Values work-life balance",
+            content="Values work-life balance highly",
+            evidence=[
+                ObservationEvidence(
+                    memory_id="mem-balance-old",
+                    quote="turned down a promotion because of the hours",
+                    relevance="Prioritized balance over advancement",
+                    timestamp=old_time,
+                ),
+                ObservationEvidence(
+                    memory_id="mem-balance-recent",
+                    quote="always log off by 6pm no matter what",
+                    relevance="Maintains boundaries",
+                    timestamp=recent_time,
+                ),
+            ],
+            created_at=now,
+        )
+
+        evidence_span = obs.evidence_span
+        assert evidence_span["from"] == old_time.isoformat()
+        assert evidence_span["to"] == recent_time.isoformat()
+
+    def test_observation_empty_evidence_span(self):
+        """Observation with no evidence should have null span."""
+        obs = Observation(
+            title="Test observation",
+            content="Test observation without evidence",
+            evidence=[],
+        )
+
+        evidence_span = obs.evidence_span
+        assert evidence_span["from"] is None
+        assert evidence_span["to"] is None
+
+
+class TestVerifyEvidenceQuotes:
+    """Tests for evidence quote verification.
+
+    This ensures the LLM isn't hallucinating quotes - every quote
+    must actually appear in the source memory.
+    """
+
+    def test_valid_quotes(self):
+        """Should return True when quotes exist in their source memories."""
+        obs = Observation(
+            title="Enjoys hiking",
+            content="Enjoys hiking on weekends",
+            evidence=[
+                ObservationEvidence(
+                    memory_id="mem-hiking-trip",
+                    quote="went hiking at Mount Tam",
+                    relevance="Shows hiking activity",
+                    timestamp=datetime.now(timezone.utc),
+                ),
+            ],
+        )
+
+        memories = {
+            "mem-hiking-trip": "Had a great Saturday - went hiking at Mount Tam with friends and saw amazing views."
+        }
+        is_valid, errors = verify_evidence_quotes(obs, memories)
+
+        assert is_valid is True
+        assert len(errors) == 0
+
+    def test_invalid_quote(self):
+        """Should return False when quote doesn't exist in memory.
+
+        This catches LLM hallucinations where it fabricates quotes.
+        """
+        obs = Observation(
+            title="Loves spicy food",
+            content="Loves spicy food",
+            evidence=[
+                ObservationEvidence(
+                    memory_id="mem-dinner",
+                    quote="I love extra hot salsa",
+                    relevance="Shows spicy food preference",
+                    timestamp=datetime.now(timezone.utc),
+                ),
+            ],
+        )
+
+        memories = {"mem-dinner": "Had tacos for dinner. The guacamole was really fresh."}
+        is_valid, errors = verify_evidence_quotes(obs, memories)
+
+        assert is_valid is False
+        assert len(errors) == 1
+        assert "Quote not found" in errors[0]
+
+    def test_missing_memory(self):
+        """Should return False when referenced memory doesn't exist.
+
+        This catches cases where the LLM references a memory ID that
+        was never actually retrieved.
+        """
+        obs = Observation(
+            title="Has a dog named Max",
+            content="Has a dog named Max",
+            evidence=[
+                ObservationEvidence(
+                    memory_id="mem-pet-story",
+                    quote="took Max to the vet",
+                    relevance="Shows pet ownership",
+                    timestamp=datetime.now(timezone.utc),
+                ),
+            ],
+        )
+
+        memories = {"mem-different-id": "Some unrelated memory content"}
+        is_valid, errors = verify_evidence_quotes(obs, memories)
+
+        assert is_valid is False
+        assert len(errors) == 1
+        assert "not found" in errors[0]
+
+
+class TestCandidateObservation:
+    """Tests for candidate observation model.
+
+    Candidates are generated in the SEED phase and validated
+    before becoming full observations.
+    """
+
+    def test_create_candidate(self):
+        """Should create candidate with content and seed memories."""
+        candidate = CandidateObservation(
+            content="User prefers async communication over meetings",
+            seed_memory_ids=["mem-slack-pref", "mem-meeting-decline"],
+        )
+
+        assert candidate.content == "User prefers async communication over meetings"
+        assert len(candidate.seed_memory_ids) == 2
+        assert "mem-slack-pref" in candidate.seed_memory_ids

hindsight-api/tests/test_observations.py

@@ -8,20 +8,9 @@ populated from the summary for backwards compatibility.
 import pytest
 from hindsight_api.engine.memory_engine import Budget
 from hindsight_api import RequestContext
-from hindsight_api.config import get_config
 from datetime import datetime, timezone
 
 
-@pytest.fixture
-def disable_observations():
-    """Disable observations for a specific test."""
-    config = get_config()
-    original_value = config.enable_observations
-    config.enable_observations = False
-    yield
-    config.enable_observations = original_value
-
-
 @pytest.mark.asyncio
 async def test_entity_extraction_on_retain(memory, request_context):
     """
@@ -381,12 +370,12 @@ async def test_get_entity_state(memory, request_context):
 
 
 @pytest.mark.asyncio
-async def test_observation_fact_type_in_database(memory, request_context, disable_observations):
+async def test_observation_fact_type_in_database(memory, request_context):
     """
-    Test that when observations are disabled, no observation records are created.
+    Test that observations are NOT stored as memory_units with fact_type='observation'.
 
-    When enable_observations=False, consolidation does not run and no
-    memory_units with fact_type='observation' should exist.
+    NOTE: Observations are now handled via mental models, not as memory_units
+    or entity summaries.
     """
     bank_id = f"test_obs_db_{datetime.now(timezone.utc).timestamp()}"
 

hindsight-api/tests/test_reflections.py

@@ -1,448 +0,0 @@
-"""Tests for mental models (formerly reflections), observations, and learnings functionality."""
-
-import uuid
-
-import pytest
-import pytest_asyncio
-import httpx
-from hindsight_api.api import create_app
-from hindsight_api.engine.memory_engine import MemoryEngine
-
-
-@pytest_asyncio.fixture
-async def api_client(memory):
-    """Create an async test client for the FastAPI app."""
-    app = create_app(memory, initialize_memory=False)
-    transport = httpx.ASGITransport(app=app)
-    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
-        yield client
-
-
-@pytest.fixture
-def test_bank_id():
-    """Provide a unique bank ID for this test run."""
-    return f"test_mental_models_{uuid.uuid4().hex[:8]}"
-
-
-class TestMentalModelsCRUD:
-    """Test mental models CRUD operations via memory engine."""
-
-    @pytest.mark.asyncio
-    async def test_create_and_get_mental_model(self, memory: MemoryEngine, request_context):
-        """Test creating and retrieving a mental model."""
-        bank_id = f"test-mental-model-{uuid.uuid4().hex[:8]}"
-
-        # Create the bank first
-        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)
-
-        # Create a mental model
-        mental_model = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Team Preferences",
-            source_query="What are the team's communication preferences?",
-            content="The team prefers async communication via Slack",
-            tags=["team"],
-            request_context=request_context,
-        )
-
-        assert mental_model["name"] == "Team Preferences"
-        assert mental_model["source_query"] == "What are the team's communication preferences?"
-        assert mental_model["content"] == "The team prefers async communication via Slack"
-        assert mental_model["tags"] == ["team"]
-        assert "id" in mental_model
-
-        # Get the mental model
-        fetched = await memory.get_mental_model(
-            bank_id=bank_id,
-            mental_model_id=mental_model["id"],
-            request_context=request_context,
-        )
-
-        assert fetched["id"] == mental_model["id"]
-        assert fetched["name"] == "Team Preferences"
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-    @pytest.mark.asyncio
-    async def test_list_mental_models(self, memory: MemoryEngine, request_context):
-        """Test listing mental models with filters."""
-        bank_id = f"test-mental-model-list-{uuid.uuid4().hex[:8]}"
-
-        # Create the bank first
-        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)
-
-        # Create multiple mental models
-        await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Mental Model 1",
-            source_query="Query 1",
-            content="Content 1",
-            tags=["tag1"],
-            request_context=request_context,
-        )
-        await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Mental Model 2",
-            source_query="Query 2",
-            content="Content 2",
-            tags=["tag2"],
-            request_context=request_context,
-        )
-
-        # List all
-        all_mental_models = await memory.list_mental_models(
-            bank_id=bank_id,
-            request_context=request_context,
-        )
-        assert len(all_mental_models) == 2
-
-        # List with tag filter
-        tag1_mental_models = await memory.list_mental_models(
-            bank_id=bank_id,
-            tags=["tag1"],
-            request_context=request_context,
-        )
-        assert len(tag1_mental_models) == 1
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-    @pytest.mark.asyncio
-    async def test_update_mental_model(self, memory: MemoryEngine, request_context):
-        """Test updating a mental model."""
-        bank_id = f"test-mental-model-update-{uuid.uuid4().hex[:8]}"
-
-        # Create the bank first
-        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)
-
-        # Create a mental model
-        mental_model = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="Original Name",
-            source_query="Original Query",
-            content="Original Content",
-            request_context=request_context,
-        )
-
-        # Update the mental model
-        updated = await memory.update_mental_model(
-            bank_id=bank_id,
-            mental_model_id=mental_model["id"],
-            name="Updated Name",
-            content="Updated Content",
-            request_context=request_context,
-        )
-
-        assert updated["name"] == "Updated Name"
-        assert updated["content"] == "Updated Content"
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-    @pytest.mark.asyncio
-    async def test_delete_mental_model(self, memory: MemoryEngine, request_context):
-        """Test deleting a mental model."""
-        bank_id = f"test-mental-model-delete-{uuid.uuid4().hex[:8]}"
-
-        # Create the bank first
-        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)
-
-        # Create a mental model
-        mental_model = await memory.create_mental_model(
-            bank_id=bank_id,
-            name="To Delete",
-            source_query="Query",
-            content="Content",
-            request_context=request_context,
-        )
-
-        # Delete the mental model
-        await memory.delete_mental_model(
-            bank_id=bank_id,
-            mental_model_id=mental_model["id"],
-            request_context=request_context,
-        )
-
-        # Verify deletion - should return None
-        fetched = await memory.get_mental_model(
-            bank_id=bank_id,
-            mental_model_id=mental_model["id"],
-            request_context=request_context,
-        )
-        assert fetched is None
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-
-class TestObservationsAPI:
-    """Test observations API endpoints.
-
-    NOTE: Observations are now stored in memory_units with fact_type='observation'
-    and accessed via recall with fact_type=["observation"]. The old /observations
-    endpoint was removed. These tests are skipped.
-    """
-
-    @pytest.mark.skip(reason="Observations endpoint removed - use recall with fact_type=['observation']")
-    @pytest.mark.asyncio
-    async def test_list_observations_empty(self, api_client, test_bank_id):
-        """Test listing observations when none exist."""
-        pass
-
-    @pytest.mark.skip(reason="Observations endpoint removed - use recall with fact_type=['observation']")
-    @pytest.mark.asyncio
-    async def test_get_observation_not_found(self, api_client, test_bank_id):
-        """Test getting a non-existent observation."""
-        pass
-
-
-class TestMentalModelsAPI:
-    """Test mental models API endpoints."""
-
-    @pytest.mark.asyncio
-    async def test_mental_models_api_crud(self, api_client, test_bank_id):
-        """Test full CRUD cycle through API."""
-        import asyncio
-
-        # Create bank first via profile endpoint
-        await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")
-
-        # Create a mental model (async operation)
-        response = await api_client.post(
-            f"/v1/default/banks/{test_bank_id}/mental-models",
-            json={
-                "name": "API Test Mental Model",
-                "source_query": "What is the API test about?",
-                "content": "This is an API test mental model",
-                "tags": ["api-test"],
-            },
-        )
-        assert response.status_code == 200
-        create_result = response.json()
-        assert "operation_id" in create_result
-        operation_id = create_result["operation_id"]
-
-        # Wait for the async operation to complete
-        for _ in range(30):  # Wait up to 30 seconds
-            response = await api_client.get(f"/v1/default/banks/{test_bank_id}/operations/{operation_id}")
-            if response.status_code == 200:
-                op_status = response.json()
-                if op_status.get("status") == "completed":
-                    break
-            await asyncio.sleep(1)
-
-        # List mental models to get the created mental model
-        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/mental-models")
-        assert response.status_code == 200
-        mental_models = response.json()["items"]
-        assert len(mental_models) >= 1
-
-        # Find our mental model
-        mental_model = next((m for m in mental_models if m["name"] == "API Test Mental Model"), None)
-        assert mental_model is not None, f"Mental model not found. Items: {mental_models}"
-        mental_model_id = mental_model["id"]
-
-        # Get the mental model
-        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/mental-models/{mental_model_id}")
-        assert response.status_code == 200
-        assert response.json()["name"] == "API Test Mental Model"
-
-        # Update the mental model
-        response = await api_client.patch(
-            f"/v1/default/banks/{test_bank_id}/mental-models/{mental_model_id}",
-            json={"name": "Updated API Test Mental Model"},
-        )
-        assert response.status_code == 200
-        assert response.json()["name"] == "Updated API Test Mental Model"
-
-        # Delete the mental model
-        response = await api_client.delete(f"/v1/default/banks/{test_bank_id}/mental-models/{mental_model_id}")
-        assert response.status_code == 200
-
-        # Verify deletion
-        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/mental-models/{mental_model_id}")
-        assert response.status_code == 404
-
-        # Cleanup
-        await api_client.delete(f"/v1/default/banks/{test_bank_id}")
-
-
-class TestRecallWithObservationsAndMentalModels:
-    """Test recall integration with observations and mental models."""
-
-    @pytest.mark.asyncio
-    async def test_recall_includes_observations(self, api_client, test_bank_id):
-        """Test that recall can include observations in the response."""
-        # Create bank first via profile endpoint
-        await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")
-
-        # Note: Observations are auto-created via consolidation, not manually
-        # This test just verifies the include parameter works
-
-        # Recall with observations included
-        response = await api_client.post(
-            f"/v1/default/banks/{test_bank_id}/memories/recall",
-            json={
-                "query": "What is machine learning?",
-                "include": {
-                    "observations": {"max_results": 5},
-                },
-            },
-        )
-        assert response.status_code == 200
-        result = response.json()
-
-        # Should have observations field in response (may be empty)
-        assert "observations" in result or result.get("observations") is None
-
-        # Cleanup
-        await api_client.delete(f"/v1/default/banks/{test_bank_id}")
-
-    @pytest.mark.asyncio
-    async def test_recall_includes_mental_models(self, api_client, test_bank_id):
-        """Test that recall can include mental models in the response."""
-        # Create bank first via profile endpoint
-        await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")
-
-        # Create a mental model first
-        response = await api_client.post(
-            f"/v1/default/banks/{test_bank_id}/mental-models",
-            json={
-                "name": "AI Overview",
-                "source_query": "What is AI?",
-                "content": "Artificial intelligence is the simulation of human intelligence",
-                "tags": [],
-            },
-        )
-        assert response.status_code == 200
-
-        # Recall with mental models included
-        response = await api_client.post(
-            f"/v1/default/banks/{test_bank_id}/memories/recall",
-            json={
-                "query": "What is artificial intelligence?",
-                "include": {
-                    "mental_models": {"max_results": 5},
-                },
-            },
-        )
-        assert response.status_code == 200
-        result = response.json()
-
-        # Should have mental_models in response (may be empty if embedding not generated yet)
-        assert "mental_models" in result or result.get("mental_models") is None
-
-        # Cleanup
-        await api_client.delete(f"/v1/default/banks/{test_bank_id}")
-
-    @pytest.mark.asyncio
-    async def test_recall_without_observations_by_default(self, api_client, test_bank_id):
-        """Test that recall does not include observations by default."""
-        # Create bank first via profile endpoint
-        await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")
-
-        # Recall without specifying observations
-        response = await api_client.post(
-            f"/v1/default/banks/{test_bank_id}/memories/recall",
-            json={
-                "query": "Test query",
-            },
-        )
-        assert response.status_code == 200
-        result = response.json()
-
-        # Observations should not be in response
-        assert result.get("observations") is None
-
-        # Cleanup
-        await api_client.delete(f"/v1/default/banks/{test_bank_id}")
-
-
-class TestReflectUsesMentalModels:
-    """Test that reflect searches and uses mental models when available."""
-
-    @pytest.mark.asyncio
-    async def test_reflect_searches_mental_models_when_available(self, memory: MemoryEngine, request_context):
-        """Test that reflect uses search_mental_models when the bank has mental models.
-
-        Given:
-        - A bank with a mental model about "team collaboration"
-
-        Expected:
-        - Reflect should call search_mental_models tool
-        - The mental model content should influence the response
-        """
-        bank_id = f"test-reflect-mm-{uuid.uuid4().hex[:8]}"
-
-        # Create the bank
-        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)
-
-        # Create a mental model about team collaboration
-        mental_model = await memory.create_mental_model(
-            bank_id=bank_id,
-            mental_model_id=str(uuid.uuid4()),
-            name="Team Collaboration Practices",
-            source_query="How does the team collaborate?",
-            content="The team uses async communication via Slack and holds daily standups at 9am. "
-            "Code reviews are required before merging. The team values documentation and "
-            "prefers written communication for complex decisions.",
-            tags=["team"],
-            request_context=request_context,
-        )
-
-        # Run reflect with a query about team collaboration
-        result = await memory.reflect_async(
-            bank_id=bank_id,
-            query="How does the team work together?",
-            request_context=request_context,
-        )
-
-        # Check that mental models were searched
-        tool_calls = result.tool_trace
-        search_mm_calls = [tc for tc in tool_calls if tc.tool == "search_mental_models"]
-
-        assert len(search_mm_calls) > 0, (
-            f"Expected search_mental_models to be called when bank has mental models. "
-            f"Tool calls: {[tc.tool for tc in tool_calls]}"
-        )
-
-        # Check that the reason field is populated for debugging
-        for tc in search_mm_calls:
-            assert tc.reason is not None, "Tool call should have a reason for debugging"
-
-        # The response should mention concepts from the mental model
-        response_text = result.text.lower()
-        has_relevant_content = any(
-            keyword in response_text
-            for keyword in ["slack", "async", "standup", "code review", "documentation", "communication"]
-        )
-        assert has_relevant_content, (
-            f"Expected response to reference mental model content. Got: {result.text[:500]}"
-        )
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)
-
-    @pytest.mark.asyncio
-    async def test_reflect_tool_trace_includes_reason(self, memory: MemoryEngine, request_context):
-        """Test that tool traces include the reason field for debugging."""
-        bank_id = f"test-reflect-reason-{uuid.uuid4().hex[:8]}"
-
-        # Create the bank
-        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)
-
-        # Run reflect - it should use observations or recall
-        result = await memory.reflect_async(
-            bank_id=bank_id,
-            query="What is the weather like?",
-            request_context=request_context,
-        )
-
-        # All tool calls should have a reason
-        for tc in result.tool_trace:
-            if tc.tool != "done":  # done doesn't need a reason
-                assert tc.reason is not None, f"Tool {tc.tool} should have a reason for debugging"
-
-        # Cleanup
-        await memory.delete_bank(bank_id, request_context=request_context)

hindsight-api/tests/test_retain.py

@@ -279,7 +279,6 @@ async def test_event_date_storage(memory, request_context):
 
 
 @pytest.mark.asyncio
-@pytest.mark.xfail(reason="LLM date extraction from content is non-deterministic", strict=False)
 async def test_temporal_ordering(memory, request_context):
     """
     Test that facts can be stored and retrieved with correct temporal ordering.
@@ -2082,117 +2081,3 @@ def test_recall_result_model_empty_construction():
     assert result.chunks == {}, "Should have empty chunks"
 
     logger.info("✓ RecallResult empty construction works correctly")
-
-
-@pytest.mark.asyncio
-async def test_custom_extraction_mode():
-    """
-    Test that custom extraction mode uses custom guidelines from env variable.
-
-    This test verifies that when HINDSIGHT_API_RETAIN_EXTRACTION_MODE=custom and
-    HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS is set, the fact extraction uses the
-    custom guidelines while keeping structural parts intact.
-    """
-    import os
-    from hindsight_api import LLMConfig
-    from hindsight_api.engine.retain.fact_extraction import extract_facts_from_text
-    from hindsight_api.config import clear_config_cache
-
-    # Save original env vars
-    original_mode = os.getenv("HINDSIGHT_API_RETAIN_EXTRACTION_MODE")
-    original_instructions = os.getenv("HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS")
-
-    try:
-        # Set custom extraction mode with challenging language-specific guidelines
-        os.environ["HINDSIGHT_API_RETAIN_EXTRACTION_MODE"] = "custom"
-        os.environ["HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS"] = """ONLY extract facts that are in ITALIAN language.
-
-DO NOT extract:
-❌ Facts in English
-❌ Facts in any other language besides Italian
-
-If the text contains both Italian and English content, extract ONLY the Italian facts."""
-
-        # Clear config cache to pick up new env vars
-        clear_config_cache()
-
-        # Test content with BOTH Italian (should extract) and English (should NOT extract) facts
-        # This is a much harder test than filtering greetings
-        text = """
-        The team discussed the new architecture. We will use microservices.
-
-        Il database PostgreSQL ha ridotto la latenza delle query del 60%.
-        Alice ha suggerito di usare il connection pooling per migliorare le prestazioni.
-
-        Bob mentioned that the API endpoint is ready for testing.
-        The deployment pipeline has been updated to use Kubernetes.
-
-        Marco ha completato la revisione del codice e ha approvato le modifiche.
-        Il sistema di autenticazione è stato migrato a OAuth 2.0.
-        """
-
-        llm_config = LLMConfig.for_memory()
-
-        facts, _, _ = await extract_facts_from_text(
-            text=text,
-            event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
-            context="team meeting notes",
-            llm_config=llm_config,
-            agent_name="TestUser"
-        )
-
-        logger.info(f"\nExtracted {len(facts)} facts with custom mode (Italian only):")
-        for i, fact in enumerate(facts):
-            logger.info(f"  {i+1}. {fact.fact}")
-
-        assert len(facts) > 0, "Should extract at least one Italian fact"
-
-        # All facts text
-        all_facts_text = " ".join([f.fact for f in facts])
-
-        # Should HAVE Italian content
-        italian_keywords = ["postgresql", "latenza", "query", "alice", "connection pooling", "prestazioni",
-                          "marco", "revisione", "codice", "autenticazione", "oauth"]
-        has_italian = any(keyword in all_facts_text.lower() for keyword in italian_keywords)
-        assert has_italian, f"Should extract Italian facts. Got: {all_facts_text}"
-
-        # Should NOT have English-only content
-        # These are facts that appear ONLY in English sections
-        english_only_keywords = ["microservices", "bob", "api endpoint", "testing", "deployment pipeline", "kubernetes"]
-
-        # Check if facts contain English-only content (this would be wrong)
-        facts_lower = all_facts_text.lower()
-        found_english_only = [kw for kw in english_only_keywords if kw in facts_lower]
-
-        if found_english_only:
-            logger.warning(f"⚠ Found English-only keywords in facts: {found_english_only}")
-            logger.warning(f"  Facts: {all_facts_text}")
-            logger.warning(f"  This may indicate the LLM is not strictly following language-specific custom guidelines")
-            # Log but don't fail - LLM behavior can vary
-        else:
-            logger.info("✓ Successfully extracted only Italian facts, ignored English facts")
-
-        # At least verify we have some Italian indicators
-        italian_indicators = ["latenza", "prestazioni", "revisione", "codice", "autenticazione"]
-        italian_count = sum(1 for ind in italian_indicators if ind in facts_lower)
-
-        assert italian_count >= 1, \
-            f"Should extract facts with Italian words. Found {italian_count} Italian indicators in: {all_facts_text}"
-
-        logger.info("✓ Custom extraction mode works with language-specific guidelines")
-        logger.info(f"✓ Extracted {len(facts)} Italian facts, found {italian_count} Italian indicators")
-
-    finally:
-        # Restore original env vars
-        if original_mode is not None:
-            os.environ["HINDSIGHT_API_RETAIN_EXTRACTION_MODE"] = original_mode
-        else:
-            os.environ.pop("HINDSIGHT_API_RETAIN_EXTRACTION_MODE", None)
-
-        if original_instructions is not None:
-            os.environ["HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS"] = original_instructions
-        else:
-            os.environ.pop("HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS", None)
-
-        # Clear cache again to restore original config
-        clear_config_cache()

hindsight-api/tests/test_schema_isolation.py

@@ -11,8 +11,8 @@ import uuid
 import pytest
 import pytest_asyncio
 
-from hindsight_api.engine.memory_engine import _current_schema, fq_table
 from hindsight_api.extensions import RequestContext, TenantContext, TenantExtension
+from hindsight_api.engine.memory_engine import _current_schema, fq_table
 from hindsight_api.migrations import run_migrations
 
 
@@ -52,11 +52,6 @@ class MultiSchemaTestTenantExtension(TenantExtension):
 
         raise AuthenticationError(f"Unknown API key: {context.api_key}")
 
-    async def list_tenants(self) -> list:
-        from hindsight_api.extensions.tenant import Tenant
-
-        return [Tenant(schema=schema) for schema in self.valid_schemas]
-
 
 async def drop_schema(conn, schema_name: str) -> None:
     """Drop a schema and all its contents."""

hindsight-api/tests/test_server_module.py

@@ -249,14 +249,15 @@ class TestServerModuleExtensionLoading:
 
 # Mock extensions for testing
 from hindsight_api.extensions import (
+    TenantExtension,
+    TenantContext,
+    RequestContext,
     OperationValidatorExtension,
+    ValidationResult,
+    RetainContext,
     RecallContext,
     ReflectContext,
-    RequestContext,
-    RetainContext,
-    TenantContext,
-    TenantExtension,
-    ValidationResult,
+    RefreshMentalModelContext,
 )
 
 
@@ -270,11 +271,6 @@ class MockTenantExtension(TenantExtension):
     async def authenticate(self, request_context: RequestContext) -> TenantContext:
         return TenantContext(schema_name="public")
 
-    async def list_tenants(self) -> list:
-        from hindsight_api.extensions.tenant import Tenant
-
-        return [Tenant(schema="public")]
-
     def set_context(self, context) -> None:
         self._context_set = True
 
@@ -293,3 +289,6 @@ class MockOperationValidator(OperationValidatorExtension):
 
     async def validate_reflect(self, ctx: ReflectContext) -> ValidationResult:
         return ValidationResult.accept()
+
+    async def validate_refresh_mental_model(self, ctx: RefreshMentalModelContext) -> ValidationResult:
+        return ValidationResult.accept()

hindsight-api/tests/test_sql_schema_safety.py

@@ -21,8 +21,6 @@ TABLES = [
     "documents",
     "chunks",
     "async_operations",
-    "directives",
-    "mental_models",
 ]
 
 # Files to scan for SQL queries

hindsight-api/tests/test_tags_visibility.py

@@ -633,12 +633,7 @@ async def test_student_tracking_visibility(api_client):
 
 @pytest.mark.asyncio
 async def test_list_tags_returns_all_tags(api_client):
-    """Test that list_tags returns all unique tags with counts.
-
-    Note: list_tags counts all memory units including observations.
-    Observations inherit tags from their source facts (for visibility security),
-    so counts may be higher than the number of stored memories.
-    """
+    """Test that list_tags returns all unique tags with counts."""
     bank_id = f"list_tags_test_{datetime.now().timestamp()}"
 
     # Store memories with various tags
@@ -667,19 +662,18 @@ async def test_list_tags_returns_all_tags(api_client):
     assert "limit" in result
     assert "offset" in result
 
-    # Verify tags exist with at least the expected counts
-    # Note: Counts may be higher due to observations inheriting source fact tags
+    # Verify tags and counts
     tags_map = {item["tag"]: item["count"] for item in result["items"]}
     assert "user:alice" in tags_map
-    assert tags_map["user:alice"] >= 3  # At least 3 memories have this tag
+    assert tags_map["user:alice"] == 3  # 3 memories have this tag
     assert "user:bob" in tags_map
-    assert tags_map["user:bob"] >= 1
+    assert tags_map["user:bob"] == 1
     assert "session:123" in tags_map
-    assert tags_map["session:123"] >= 1
+    assert tags_map["session:123"] == 1
     assert "session:456" in tags_map
-    assert tags_map["session:456"] >= 1
+    assert tags_map["session:456"] == 1
 
-    assert result["total"] >= 4  # At least 4 unique tags
+    assert result["total"] == 4  # 4 unique tags
 
 
 @pytest.mark.asyncio

hindsight-api/tests/test_temporal_ranges.py

@@ -7,7 +7,6 @@ from hindsight_api import RequestContext
 
 
 @pytest.mark.asyncio
-@pytest.mark.xfail(reason="LLM date extraction from content is non-deterministic", strict=False)
 async def test_temporal_ranges_are_written(memory, request_context):
     """Test that occurred_start, occurred_end, and mentioned_at are actually written to database."""
     bank_id = "test_temporal_ranges"

hindsight-api/tests/test_worker.py

@@ -162,11 +162,6 @@ class TestWorkerPoller:
         claimed = await poller.claim_batch()
         assert len(claimed) == 3
 
-        # ClaimedTask objects have operation_id, task_dict, schema attributes
-        for task in claimed:
-            assert task.operation_id is not None
-            assert task.task_dict is not None
-
         # Verify tasks are marked as processing with worker_id
         rows = await pool.fetch(
             "SELECT status, worker_id FROM async_operations WHERE bank_id = $1",
@@ -211,7 +206,6 @@ class TestWorkerPoller:
     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
-        from hindsight_api.worker.poller import ClaimedTask
 
         # Create a pending task
         bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
@@ -240,8 +234,7 @@ class TestWorkerPoller:
 
         # Execute the task
         task_dict = json.loads(payload)
-        claimed_task = ClaimedTask(operation_id=str(op_id), task_dict=task_dict, schema=None)
-        await poller.execute_task(claimed_task)
+        await poller.execute_task(str(op_id), task_dict)
 
         assert len(executed) == 1
 
@@ -257,7 +250,6 @@ class TestWorkerPoller:
     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
-        from hindsight_api.worker.poller import ClaimedTask
 
         # Create a pending task with retry_count=0
         bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
@@ -285,8 +277,7 @@ class TestWorkerPoller:
 
         # Execute (should fail and retry)
         task_dict = json.loads(payload)
-        claimed_task = ClaimedTask(operation_id=str(op_id), task_dict=task_dict, schema=None)
-        await poller.execute_task(claimed_task)
+        await poller.execute_task(str(op_id), task_dict)
 
         # Verify task is back to pending with incremented retry_count
         row = await pool.fetchrow(
@@ -301,7 +292,6 @@ class TestWorkerPoller:
     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
-        from hindsight_api.worker.poller import ClaimedTask
 
         # Create a task that has already used all retries
         bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
@@ -329,8 +319,7 @@ class TestWorkerPoller:
 
         # Execute (should fail permanently)
         task_dict = json.loads(payload)
-        claimed_task = ClaimedTask(operation_id=str(op_id), task_dict=task_dict, schema=None)
-        await poller.execute_task(claimed_task)
+        await poller.execute_task(str(op_id), task_dict)
 
         # Verify task is marked as failed
         row = await pool.fetchrow(
@@ -340,239 +329,6 @@ class TestWorkerPoller:
         assert row["status"] == "failed"
         assert "Max retries" in row["error_message"]
 
-    @pytest.mark.asyncio
-    async def test_claim_batch_skips_consolidation_when_same_bank_processing(self, pool, clean_operations):
-        """Test that pending consolidation is skipped if same bank has one processing."""
-        from hindsight_api.worker import WorkerPoller
-
-        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
-
-        # Create a processing consolidation for bank
-        processing_op_id = uuid.uuid4()
-        await pool.execute(
-            """
-            INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload, worker_id)
-            VALUES ($1, $2, 'consolidation', 'processing', $3::jsonb, 'other-worker')
-            """,
-            processing_op_id,
-            bank_id,
-            json.dumps({"type": "consolidation", "bank_id": bank_id}),
-        )
-
-        # Create a pending consolidation for same bank (should be skipped)
-        pending_op_id = uuid.uuid4()
-        await pool.execute(
-            """
-            INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload)
-            VALUES ($1, $2, 'consolidation', 'pending', $3::jsonb)
-            """,
-            pending_op_id,
-            bank_id,
-            json.dumps({"type": "consolidation", "bank_id": bank_id}),
-        )
-
-        # Create a pending consolidation for different bank (should be claimed)
-        other_bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
-        other_op_id = uuid.uuid4()
-        await pool.execute(
-            """
-            INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload)
-            VALUES ($1, $2, 'consolidation', 'pending', $3::jsonb)
-            """,
-            other_op_id,
-            other_bank_id,
-            json.dumps({"type": "consolidation", "bank_id": other_bank_id}),
-        )
-
-        poller = WorkerPoller(
-            pool=pool,
-            worker_id="test-worker-1",
-            executor=lambda x: None,
-            batch_size=10,
-        )
-
-        claimed = await poller.claim_batch()
-
-        # Should only claim the consolidation for the other bank
-        assert len(claimed) == 1
-        assert claimed[0].operation_id == str(other_op_id)
-        assert claimed[0].task_dict["bank_id"] == other_bank_id
-
-        # Verify the pending consolidation for first bank is still pending
-        row = await pool.fetchrow(
-            "SELECT status, worker_id FROM async_operations WHERE operation_id = $1",
-            pending_op_id,
-        )
-        assert row["status"] == "pending"
-        assert row["worker_id"] is None
-
-    @pytest.mark.asyncio
-    async def test_claim_batch_allows_non_consolidation_when_consolidation_processing(self, pool, clean_operations):
-        """Test that non-consolidation tasks are still claimed even if consolidation is processing."""
-        from hindsight_api.worker import WorkerPoller
-
-        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
-
-        # Create a processing consolidation for bank
-        await pool.execute(
-            """
-            INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload, worker_id)
-            VALUES ($1, $2, 'consolidation', 'processing', $3::jsonb, 'other-worker')
-            """,
-            uuid.uuid4(),
-            bank_id,
-            json.dumps({"type": "consolidation", "bank_id": bank_id}),
-        )
-
-        # Create a pending retain task for same bank (should be claimed)
-        retain_op_id = uuid.uuid4()
-        await pool.execute(
-            """
-            INSERT INTO async_operations (operation_id, bank_id, operation_type, status, task_payload)
-            VALUES ($1, $2, 'retain', 'pending', $3::jsonb)
-            """,
-            retain_op_id,
-            bank_id,
-            json.dumps({"type": "batch_retain", "bank_id": bank_id}),
-        )
-
-        poller = WorkerPoller(
-            pool=pool,
-            worker_id="test-worker-1",
-            executor=lambda x: None,
-            batch_size=10,
-        )
-
-        claimed = await poller.claim_batch()
-
-        # Should claim the retain task (non-consolidation tasks are unaffected)
-        assert len(claimed) == 1
-        assert claimed[0].operation_id == str(retain_op_id)
-
-
-class TestWorkerRecovery:
-    """Tests for worker task recovery on startup."""
-
-    @pytest.mark.asyncio
-    async def test_recover_own_tasks_resets_processing_to_pending(self, pool, clean_operations):
-        """Test that recover_own_tasks resets processing tasks back to pending."""
-        from hindsight_api.worker import WorkerPoller
-
-        # Create tasks that were being processed by this worker (simulating a crash)
-        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
-        worker_id = "crashed-worker"
-        task_ids = []
-
-        for i in range(3):
-            op_id = uuid.uuid4()
-            task_ids.append(op_id)
-            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,
-            )
-
-        # Create poller with same worker_id and call recover
-        poller = WorkerPoller(
-            pool=pool,
-            worker_id=worker_id,
-            executor=lambda x: None,
-        )
-
-        recovered_count = await poller.recover_own_tasks()
-        assert recovered_count == 3
-
-        # Verify all tasks are back to pending with no worker assigned
-        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_recover_own_tasks_does_not_affect_other_workers(self, pool, clean_operations):
-        """Test that recover_own_tasks only affects tasks from the same worker_id."""
-        from hindsight_api.worker import WorkerPoller
-
-        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
-
-        # Create tasks for worker-1 (the one that will recover)
-        for i in range(2):
-            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 (should not be affected)
-        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, 'worker-2')
-                """,
-                op_id,
-                bank_id,
-                payload,
-            )
-
-        # Worker-1 recovers its tasks
-        poller = WorkerPoller(
-            pool=pool,
-            worker_id="worker-1",
-            executor=lambda x: None,
-        )
-
-        recovered_count = await poller.recover_own_tasks()
-        assert recovered_count == 2
-
-        # 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) == 2
-
-        # 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) == 2
-        for row in worker2_rows:
-            assert row["status"] == "processing"
-
-    @pytest.mark.asyncio
-    async def test_recover_own_tasks_returns_zero_when_no_stale_tasks(self, pool, clean_operations):
-        """Test that recover_own_tasks returns 0 when there are no stale tasks."""
-        from hindsight_api.worker import WorkerPoller
-
-        poller = WorkerPoller(
-            pool=pool,
-            worker_id="fresh-worker",
-            executor=lambda x: None,
-        )
-
-        recovered_count = await poller.recover_own_tasks()
-        assert recovered_count == 0
-
 
 class TestConcurrentWorkers:
     """Tests for concurrent worker task claiming (FOR UPDATE SKIP LOCKED)."""
@@ -610,7 +366,7 @@ class TestConcurrentWorkers:
                 batch_size=5,  # Each worker tries to claim 5
             )
             claimed = await poller.claim_batch()
-            workers_claimed[worker_id] = [task.operation_id for task in claimed]
+            workers_claimed[worker_id] = [op_id for op_id, _ in claimed]
 
         # Run all workers concurrently
         await asyncio.gather(
@@ -834,186 +590,3 @@ class TestSyncTaskBackend:
 
         # Should not raise, error is logged
         await backend.submit_task({"type": "test"})
-
-
-class TestDynamicTenantDiscovery:
-    """Tests for dynamic tenant discovery via TenantExtension."""
-
-    @pytest.mark.asyncio
-    async def test_poller_discovers_tenants_dynamically(self, pool, clean_operations):
-        """Test that poller calls list_tenants() on each poll cycle."""
-        from hindsight_api.extensions.tenant import Tenant, TenantExtension
-        from hindsight_api.worker import WorkerPoller
-
-        # Create a mock tenant extension that tracks calls
-        class MockTenantExtension(TenantExtension):
-            def __init__(self):
-                self.list_tenants_calls = 0
-                self.tenants_to_return: list[Tenant] = [Tenant(schema="public")]
-
-            async def authenticate(self, context):
-                raise NotImplementedError("Not used in this test")
-
-            async def list_tenants(self) -> list[Tenant]:
-                self.list_tenants_calls += 1
-                return self.tenants_to_return
-
-        mock_extension = MockTenantExtension()
-
-        # Create pending tasks in public schema
-        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
-        for i in range(2):
-            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,
-            )
-
-        poller = WorkerPoller(
-            pool=pool,
-            worker_id="test-worker-1",
-            executor=lambda x: None,
-            batch_size=10,
-            tenant_extension=mock_extension,
-        )
-
-        # First claim_batch should call list_tenants
-        claimed1 = await poller.claim_batch()
-        assert mock_extension.list_tenants_calls == 1
-        assert len(claimed1) == 2
-
-        # Add more tasks
-        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)
-                VALUES ($1, $2, 'test', 'pending', $3::jsonb)
-                """,
-                op_id,
-                bank_id,
-                payload,
-            )
-
-        # Second claim_batch should call list_tenants again
-        claimed2 = await poller.claim_batch()
-        assert mock_extension.list_tenants_calls == 2
-        assert len(claimed2) == 2
-
-    @pytest.mark.asyncio
-    async def test_poller_picks_up_new_tenants_without_restart(self, pool, clean_operations):
-        """Test that new tenants are discovered on subsequent poll cycles."""
-        from hindsight_api.extensions.tenant import Tenant, TenantExtension
-        from hindsight_api.worker import WorkerPoller
-
-        class DynamicTenantExtension(TenantExtension):
-            def __init__(self):
-                # Start with just public
-                self.tenants: list[Tenant] = [Tenant(schema="public")]
-                self.list_tenants_calls = 0
-
-            async def authenticate(self, context):
-                raise NotImplementedError("Not used in this test")
-
-            async def list_tenants(self) -> list[Tenant]:
-                self.list_tenants_calls += 1
-                return self.tenants
-
-        dynamic_extension = DynamicTenantExtension()
-
-        # Create a task in public schema
-        bank_id = f"test-worker-{uuid.uuid4().hex[:8]}"
-        op_id = uuid.uuid4()
-        payload = json.dumps({"type": "test_task", "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,
-        )
-
-        poller = WorkerPoller(
-            pool=pool,
-            worker_id="test-worker-1",
-            executor=lambda x: None,
-            batch_size=10,
-            tenant_extension=dynamic_extension,
-        )
-
-        # First poll - only public schema
-        claimed1 = await poller.claim_batch()
-        assert len(claimed1) == 1
-        assert claimed1[0].schema is None  # public is represented as None
-        assert dynamic_extension.list_tenants_calls == 1
-
-        # Simulate tenant list changing (but we won't add a non-existent schema)
-        # In real world, the schema would be created before list_tenants returns it
-        # Here we just verify that list_tenants is called again
-
-        # Add another task to public
-        op_id2 = uuid.uuid4()
-        payload2 = json.dumps({"type": "test_task", "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_id2,
-            bank_id,
-            payload2,
-        )
-
-        # Second poll - list_tenants should be called again
-        claimed2 = await poller.claim_batch()
-        assert len(claimed2) == 1
-        assert dynamic_extension.list_tenants_calls == 2  # Called again on second poll
-
-        # Third poll with no tasks - still calls list_tenants
-        claimed3 = await poller.claim_batch()
-        assert len(claimed3) == 0
-        assert dynamic_extension.list_tenants_calls == 3  # Called again even with no tasks
-
-    @pytest.mark.asyncio
-    async def test_poller_without_tenant_extension_uses_public(self, pool, clean_operations):
-        """Test that poller uses public schema when no tenant extension is configured."""
-        from hindsight_api.worker import WorkerPoller
-
-        # Create 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,
-            )
-
-        # No tenant_extension provided
-        poller = WorkerPoller(
-            pool=pool,
-            worker_id="test-worker-1",
-            executor=lambda x: None,
-            batch_size=10,
-        )
-
-        claimed = await poller.claim_batch()
-        assert len(claimed) == 3
-
-        # All tasks should have schema=None (public)
-        for task in claimed:
-            assert task.schema is None

hindsight-cli/smoke-test.sh

@@ -115,10 +115,31 @@ 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: List operations
+# 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 16: Delete bank
+# Test 23: Delete bank
 run_test "delete bank" "$HINDSIGHT_CLI" bank delete "$TEST_BANK" -y || FAILED=1
 
 echo ""

hindsight-cli/src/api.rs

@@ -173,7 +173,7 @@ impl ApiClient {
     pub fn poll_operation(&self, agent_id: &str, operation_id: &str, verbose: bool) -> Result<(bool, Option<String>)> {
         self.runtime.block_on(async {
             loop {
-                let response = self.client.list_operations(agent_id, None, None, None, None).await?;
+                let response = self.client.list_operations(agent_id, None).await?;
                 let ops = response.into_inner();
 
                 // Find our operation
@@ -258,7 +258,7 @@ impl ApiClient {
 
     pub fn list_operations(&self, agent_id: &str, _verbose: bool) -> Result<OperationsResponse> {
         self.runtime.block_on(async {
-            let response = self.client.list_operations(agent_id, None, None, None, None).await?;
+            let response = self.client.list_operations(agent_id, None).await?;
             let value = response.into_inner();
             // Convert to JSON Value first, then parse into our type
             let json_value = serde_json::to_value(&value)?;
@@ -321,6 +321,144 @@ impl ApiClient {
 // ============================================================================
 
 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> {
@@ -436,134 +574,6 @@ impl ApiClient {
             Ok(response.into_inner())
         })
     }
-
-    // --- Mental Model Methods ---
-
-    pub fn list_mental_models(&self, bank_id: &str, _verbose: bool) -> Result<types::MentalModelListResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.list_mental_models(bank_id, None, None, None, None, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn get_mental_model(&self, bank_id: &str, mental_model_id: &str, _verbose: bool) -> Result<types::MentalModelResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.get_mental_model(bank_id, mental_model_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn create_mental_model(
-        &self,
-        bank_id: &str,
-        request: &types::CreateMentalModelRequest,
-        _verbose: bool,
-    ) -> Result<types::CreateMentalModelResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.create_mental_model(bank_id, None, request).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn update_mental_model(
-        &self,
-        bank_id: &str,
-        mental_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, mental_model_id, None, request).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn delete_mental_model(&self, bank_id: &str, mental_model_id: &str, _verbose: bool) -> Result<serde_json::Value> {
-        self.runtime.block_on(async {
-            let response = self.client.delete_mental_model(bank_id, mental_model_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn refresh_mental_model(&self, bank_id: &str, mental_model_id: &str, _verbose: bool) -> Result<types::AsyncOperationSubmitResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.refresh_mental_model(bank_id, mental_model_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    // --- Directive Methods ---
-
-    pub fn list_directives(&self, bank_id: &str, _verbose: bool) -> Result<types::DirectiveListResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.list_directives(bank_id, None, None, None, None, None, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn get_directive(&self, bank_id: &str, directive_id: &str, _verbose: bool) -> Result<types::DirectiveResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.get_directive(bank_id, directive_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn create_directive(
-        &self,
-        bank_id: &str,
-        request: &types::CreateDirectiveRequest,
-        _verbose: bool,
-    ) -> Result<types::DirectiveResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.create_directive(bank_id, None, request).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn update_directive(
-        &self,
-        bank_id: &str,
-        directive_id: &str,
-        request: &types::UpdateDirectiveRequest,
-        _verbose: bool,
-    ) -> Result<types::DirectiveResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.update_directive(bank_id, directive_id, None, request).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn delete_directive(&self, bank_id: &str, directive_id: &str, _verbose: bool) -> Result<serde_json::Value> {
-        self.runtime.block_on(async {
-            let response = self.client.delete_directive(bank_id, directive_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    // --- Consolidation Methods ---
-
-    pub fn trigger_consolidation(&self, bank_id: &str, _verbose: bool) -> Result<types::ConsolidationResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.trigger_consolidation(bank_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    pub fn clear_observations(&self, bank_id: &str, _verbose: bool) -> Result<types::DeleteResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.clear_observations(bank_id, None).await?;
-            Ok(response.into_inner())
-        })
-    }
-
-    // --- Version Methods ---
-
-    pub fn get_version(&self, _verbose: bool) -> Result<types::VersionResponse> {
-        self.runtime.block_on(async {
-            let response = self.client.get_version().await?;
-            Ok(response.into_inner())
-        })
-    }
 }
 
 // Re-export types from the generated client for use in commands

hindsight-cli/src/commands/bank.rs

@@ -495,96 +495,3 @@ pub fn delete(
         Err(e) => Err(e)
     }
 }
-
-/// Trigger consolidation to create/update observations
-pub fn consolidate(
-    client: &ApiClient,
-    bank_id: &str,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Triggering consolidation..."))
-    } else {
-        None
-    };
-
-    let response = client.trigger_consolidation(bank_id, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_success("Consolidation triggered");
-                println!("  {} {}", ui::dim("Operation ID:"), result.operation_id);
-                if result.deduplicated {
-                    println!("  {} {}", ui::dim("Note:"), "Reusing existing pending consolidation task");
-                }
-                println!();
-                println!("{}", ui::dim("Use 'hindsight operation get' to check the operation status."));
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Clear all observations for a bank
-pub fn clear_observations(
-    client: &ApiClient,
-    bank_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 clear all observations for bank '{}'? This cannot be undone.",
-            bank_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("Clearing observations..."))
-    } else {
-        None
-    };
-
-    let response = client.clear_observations(bank_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!("Observations cleared for bank '{}'", bank_id));
-                    if let Some(count) = result.deleted_count {
-                        println!("  Observations deleted: {}", count);
-                    }
-                } else {
-                    ui::print_error("Failed to clear observations");
-                }
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}

hindsight-cli/src/commands/directive.rs

@@ -1,266 +0,0 @@
-//! Directive commands for managing behavioral rules.
-
-use anyhow::Result;
-
-use crate::api::ApiClient;
-use crate::output::{self, OutputFormat};
-use crate::ui;
-
-use hindsight_client::types;
-
-/// List directives for a bank
-pub fn list(
-    client: &ApiClient,
-    bank_id: &str,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching directives..."))
-    } else {
-        None
-    };
-
-    let response = client.list_directives(bank_id, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_section_header(&format!("Directives: {}", bank_id));
-
-                if result.items.is_empty() {
-                    println!("  {}", ui::dim("No directives found."));
-                } else {
-                    for directive in &result.items {
-                        let status = if directive.is_active {
-                            ui::gradient_start("active")
-                        } else {
-                            ui::dim("inactive")
-                        };
-                        println!(
-                            "  {} {} [{}]",
-                            ui::gradient_start(&directive.id),
-                            directive.name,
-                            status
-                        );
-
-                        // Show content preview
-                        let preview: String = directive.content.chars().take(80).collect();
-                        let ellipsis = if directive.content.len() > 80 { "..." } else { "" };
-                        println!("    {}{}", ui::dim(&preview), ellipsis);
-
-                        println!();
-                    }
-                }
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Get a specific directive
-pub fn get(
-    client: &ApiClient,
-    bank_id: &str,
-    directive_id: &str,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching directive..."))
-    } else {
-        None
-    };
-
-    let response = client.get_directive(bank_id, directive_id, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(directive) => {
-            if output_format == OutputFormat::Pretty {
-                print_directive_detail(&directive);
-            } else {
-                output::print_output(&directive, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Create a new directive
-pub fn create(
-    client: &ApiClient,
-    bank_id: &str,
-    name: &str,
-    content: &str,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Creating directive..."))
-    } else {
-        None
-    };
-
-    let request = types::CreateDirectiveRequest {
-        name: name.to_string(),
-        content: content.to_string(),
-        is_active: true,
-        priority: 0,
-        tags: vec![],
-    };
-
-    let response = client.create_directive(bank_id, &request, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(directive) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Directive '{}' created successfully", directive.id));
-                println!();
-                print_directive_detail(&directive);
-            } else {
-                output::print_output(&directive, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Update a directive
-pub fn update(
-    client: &ApiClient,
-    bank_id: &str,
-    directive_id: &str,
-    name: Option<String>,
-    content: Option<String>,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    if name.is_none() && content.is_none() {
-        anyhow::bail!("At least one of --name or --content must be provided");
-    }
-
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Updating directive..."))
-    } else {
-        None
-    };
-
-    let request = types::UpdateDirectiveRequest {
-        name,
-        content,
-        is_active: None,
-        priority: None,
-        tags: None,
-    };
-
-    let response = client.update_directive(bank_id, directive_id, &request, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(directive) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Directive '{}' updated successfully", directive_id));
-                println!();
-                print_directive_detail(&directive);
-            } else {
-                output::print_output(&directive, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Delete a directive
-pub fn delete(
-    client: &ApiClient,
-    bank_id: &str,
-    directive_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 directive '{}'? This cannot be undone.",
-            directive_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 directive..."))
-    } else {
-        None
-    };
-
-    let response = client.delete_directive(bank_id, directive_id, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(_) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Directive '{}' deleted successfully", directive_id));
-            } else {
-                println!("{{\"success\": true}}");
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-// Helper function to print directive details
-fn print_directive_detail(directive: &types::DirectiveResponse) {
-    ui::print_section_header(&directive.name);
-
-    println!("  {} {}", ui::dim("ID:"), ui::gradient_start(&directive.id));
-
-    let status = if directive.is_active {
-        ui::gradient_start("active")
-    } else {
-        ui::dim("inactive")
-    };
-    println!("  {} {}", ui::dim("Status:"), status);
-    println!("  {} {}", ui::dim("Priority:"), directive.priority);
-
-    if !directive.tags.is_empty() {
-        println!("  {} {}", ui::dim("Tags:"), directive.tags.join(", "));
-    }
-
-    println!();
-    println!("{}", ui::gradient_text("─── Content ───"));
-    println!();
-    println!("{}", &directive.content);
-    println!();
-}

hindsight-cli/src/commands/health.rs

@@ -75,45 +75,6 @@ pub fn health(
     }
 }
 
-/// Get API version information
-pub fn version(
-    client: &ApiClient,
-    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_version(verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(result) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_section_header("API Version");
-                println!("  {} {}", ui::dim("Version:"), result.api_version);
-
-                println!();
-                println!("  {}", ui::dim("Features:"));
-                println!("    {} MCP Server: {}", ui::gradient_start("•"), if result.features.mcp { "enabled" } else { "disabled" });
-                println!("    {} Observations: {}", ui::gradient_start("•"), if result.features.observations { "enabled" } else { "disabled" });
-                println!("    {} Background Worker: {}", ui::gradient_start("•"), if result.features.worker { "enabled" } else { "disabled" });
-                println!();
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
 /// Get Prometheus metrics
 pub fn metrics(
     client: &ApiClient,

hindsight-cli/src/commands/mental_model.rs

@@ -1,17 +1,56 @@
-//! Mental model commands for managing user-curated summaries.
+//! Mental model commands for managing structured knowledge containers.
 
-use anyhow::Result;
+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<()> {
@@ -21,7 +60,13 @@ pub fn list(
         None
     };
 
-    let response = client.list_mental_models(bank_id, verbose);
+    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();
@@ -35,17 +80,36 @@ pub fn list(
                 if result.items.is_empty() {
                     println!("  {}", ui::dim("No mental models found."));
                 } else {
-                    for mental_model in &result.items {
+                    for model in &result.items {
+                        let subtype_str = &model.subtype;
+                        let obs_count = model.observations.len();
+
                         println!(
-                            "  {} {}",
-                            ui::gradient_start(&mental_model.id),
-                            mental_model.name
+                            "  {} {} {}",
+                            ui::gradient_start(&model.id),
+                            ui::dim(&format!("[{}]", subtype_str)),
+                            model.name
                         );
 
-                        // Show content preview
-                        let preview: String = mental_model.content.chars().take(80).collect();
-                        let ellipsis = if mental_model.content.len() > 80 { "..." } else { "" };
-                        println!("    {}{}", ui::dim(&preview), ellipsis);
+                        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!();
                     }
@@ -63,7 +127,7 @@ pub fn list(
 pub fn get(
     client: &ApiClient,
     bank_id: &str,
-    mental_model_id: &str,
+    model_id: &str,
     verbose: bool,
     output_format: OutputFormat,
 ) -> Result<()> {
@@ -73,18 +137,18 @@ pub fn get(
         None
     };
 
-    let response = client.get_mental_model(bank_id, mental_model_id, verbose);
+    let response = client.get_mental_model(bank_id, model_id, verbose);
 
     if let Some(mut sp) = spinner {
         sp.finish();
     }
 
     match response {
-        Ok(mental_model) => {
+        Ok(model) => {
             if output_format == OutputFormat::Pretty {
-                print_mental_model_detail(&mental_model);
+                print_mental_model_detail(&model);
             } else {
-                output::print_output(&mental_model, output_format)?;
+                output::print_output(&model, output_format)?;
             }
             Ok(())
         }
@@ -97,7 +161,10 @@ pub fn create(
     client: &ApiClient,
     bank_id: &str,
     name: &str,
-    source_query: &str,
+    description: &str,
+    subtype: Option<String>,
+    tags: Option<Vec<String>>,
+    observations_file: Option<PathBuf>,
     verbose: bool,
     output_format: OutputFormat,
 ) -> Result<()> {
@@ -107,12 +174,23 @@ pub fn create(
         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(),
-        source_query: source_query.to_string(),
-        max_tokens: 2048,
-        tags: vec![],
-        trigger: None,
+        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);
@@ -122,59 +200,13 @@ pub fn create(
     }
 
     match response {
-        Ok(result) => {
+        Ok(model) => {
             if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Mental model created, operation_id: {}", result.operation_id));
-            } else {
-                output::print_output(&result, output_format)?;
-            }
-            Ok(())
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Update a mental model
-pub fn update(
-    client: &ApiClient,
-    bank_id: &str,
-    mental_model_id: &str,
-    name: Option<String>,
-    verbose: bool,
-    output_format: OutputFormat,
-) -> Result<()> {
-    if name.is_none() {
-        anyhow::bail!("--name must be provided");
-    }
-
-    let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Updating mental model..."))
-    } else {
-        None
-    };
-
-    let request = types::UpdateMentalModelRequest {
-        name,
-        source_query: None,
-        max_tokens: None,
-        tags: None,
-        trigger: None,
-    };
-
-    let response = client.update_mental_model(bank_id, mental_model_id, &request, verbose);
-
-    if let Some(mut sp) = spinner {
-        sp.finish();
-    }
-
-    match response {
-        Ok(mental_model) => {
-            if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Mental model '{}' updated successfully", mental_model_id));
+                ui::print_success(&format!("Mental model '{}' created successfully", model.id));
                 println!();
-                print_mental_model_detail(&mental_model);
+                print_mental_model_detail(&model);
             } else {
-                output::print_output(&mental_model, output_format)?;
+                output::print_output(&model, output_format)?;
             }
             Ok(())
         }
@@ -186,7 +218,7 @@ pub fn update(
 pub fn delete(
     client: &ApiClient,
     bank_id: &str,
-    mental_model_id: &str,
+    model_id: &str,
     yes: bool,
     verbose: bool,
     output_format: OutputFormat,
@@ -195,7 +227,7 @@ pub fn delete(
     if !yes && output_format == OutputFormat::Pretty {
         let message = format!(
             "Are you sure you want to delete mental model '{}'? This cannot be undone.",
-            mental_model_id
+            model_id
         );
 
         let confirmed = ui::prompt_confirmation(&message)?;
@@ -212,18 +244,22 @@ pub fn delete(
         None
     };
 
-    let response = client.delete_mental_model(bank_id, mental_model_id, verbose);
+    let response = client.delete_mental_model(bank_id, model_id, verbose);
 
     if let Some(mut sp) = spinner {
         sp.finish();
     }
 
     match response {
-        Ok(_) => {
+        Ok(result) => {
             if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Mental model '{}' deleted successfully", mental_model_id));
+                if result.success {
+                    ui::print_success(&format!("Mental model '{}' deleted successfully", model_id));
+                } else {
+                    ui::print_error("Failed to delete mental model");
+                }
             } else {
-                println!("{{\"success\": true}}");
+                output::print_output(&result, output_format)?;
             }
             Ok(())
         }
@@ -231,38 +267,214 @@ pub fn delete(
     }
 }
 
-/// Refresh a mental model
-pub fn refresh(
+/// Update a mental model's name or description
+pub fn update(
     client: &ApiClient,
     bank_id: &str,
-    mental_model_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("Submitting mental model refresh..."))
+        Some(ui::create_spinner("Updating mental model..."))
     } else {
         None
     };
 
-    let response = client.refresh_mental_model(bank_id, mental_model_id, verbose);
+    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(operation) => {
+        Ok(model) => {
             if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!(
-                    "Mental model refresh submitted. Operation ID: {}",
-                    operation.operation_id
-                ));
-                println!("  {} {}", ui::dim("Status:"), operation.status);
+                ui::print_success(&format!("Mental model '{}' updated successfully", model_id));
                 println!();
-                println!("{}", ui::dim("Use 'hindsight operations get' to check the operation status."));
+                print_mental_model_detail(&model);
             } else {
-                output::print_output(&operation, output_format)?;
+                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(())
         }
@@ -271,15 +483,239 @@ pub fn refresh(
 }
 
 // Helper function to print mental model details
-fn print_mental_model_detail(mental_model: &types::MentalModelResponse) {
-    ui::print_section_header(&mental_model.name);
+fn print_mental_model_detail(model: &types::MentalModelResponse) {
+    ui::print_section_header(&model.name);
 
-    println!("  {} {}", ui::dim("ID:"), ui::gradient_start(&mental_model.id));
-    println!("  {} {}", ui::dim("Source Query:"), &mental_model.source_query);
+    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("─── Content ───"));
+    println!("{}", ui::gradient_text("─── Observations ───"));
     println!();
-    println!("{}", &mental_model.content);
+
+    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,11 +1,10 @@
 pub mod bank;
 pub mod chunk;
-pub mod directive;
 pub mod document;
 pub mod entity;
 pub mod explore;
 pub mod health;
 pub mod memory;
-pub mod operation;
 pub mod mental_model;
+pub mod operation;
 pub mod tag;

hindsight-cli/src/main.rs

@@ -75,6 +75,10 @@ enum Commands {
     #[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),
@@ -95,23 +99,12 @@ enum Commands {
     #[command(subcommand)]
     Operation(OperationCommands),
 
-    /// Manage mental models (user-curated summaries)
-    #[command(subcommand)]
-    MentalModel(MentalModelCommands),
-
-    /// Manage directives (behavioral rules)
-    #[command(subcommand)]
-    Directive(DirectiveCommands),
-
     /// Check API health status
     Health,
 
     /// Get Prometheus metrics
     Metrics,
 
-    /// Get API version information
-    Version,
-
     /// Interactive TUI explorer (k9s-style) for navigating banks, memories, entities, and performing recall/reflect
     #[command(alias = "tui")]
     Explore,
@@ -255,22 +248,6 @@ enum BankCommands {
         #[arg(short = 'y', long)]
         yes: bool,
     },
-
-    /// Trigger consolidation to create/update observations
-    Consolidate {
-        /// Bank ID
-        bank_id: String,
-    },
-
-    /// Clear all observations for a bank
-    ClearObservations {
-        /// Bank ID
-        bank_id: String,
-
-        /// Skip confirmation prompt
-        #[arg(short = 'y', long)]
-        yes: bool,
-    },
 }
 
 #[derive(Subcommand)]
@@ -527,6 +504,134 @@ 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
@@ -557,131 +662,6 @@ enum ChunkCommands {
     },
 }
 
-#[derive(Subcommand)]
-enum MentalModelCommands {
-    /// List mental models for a bank
-    List {
-        /// Bank ID
-        bank_id: String,
-    },
-
-    /// Get a specific mental model
-    Get {
-        /// Bank ID
-        bank_id: String,
-
-        /// Mental model ID
-        mental_model_id: String,
-    },
-
-    /// Create a new mental model
-    Create {
-        /// Bank ID
-        bank_id: String,
-
-        /// Mental model name
-        name: String,
-
-        /// Source query to generate the mental model from
-        source_query: String,
-    },
-
-    /// Update a mental model
-    Update {
-        /// Bank ID
-        bank_id: String,
-
-        /// Mental model ID
-        mental_model_id: String,
-
-        /// New name
-        #[arg(long)]
-        name: Option<String>,
-    },
-
-    /// Delete a mental model
-    Delete {
-        /// Bank ID
-        bank_id: String,
-
-        /// Mental model ID
-        mental_model_id: String,
-
-        /// Skip confirmation prompt
-        #[arg(short = 'y', long)]
-        yes: bool,
-    },
-
-    /// Refresh a mental model (re-run the source query)
-    Refresh {
-        /// Bank ID
-        bank_id: String,
-
-        /// Mental model ID
-        mental_model_id: String,
-    },
-}
-
-#[derive(Subcommand)]
-enum DirectiveCommands {
-    /// List directives for a bank
-    List {
-        /// Bank ID
-        bank_id: String,
-    },
-
-    /// Get a specific directive
-    Get {
-        /// Bank ID
-        bank_id: String,
-
-        /// Directive ID
-        directive_id: String,
-    },
-
-    /// Create a new directive
-    Create {
-        /// Bank ID
-        bank_id: String,
-
-        /// Directive name
-        name: String,
-
-        /// Directive content (the text to inject into prompts)
-        content: String,
-    },
-
-    /// Update a directive
-    Update {
-        /// Bank ID
-        bank_id: String,
-
-        /// Directive ID
-        directive_id: String,
-
-        /// New name
-        #[arg(long)]
-        name: Option<String>,
-
-        /// New content
-        #[arg(long)]
-        content: Option<String>,
-    },
-
-    /// Delete a directive
-    Delete {
-        /// Bank ID
-        bank_id: String,
-
-        /// Directive ID
-        directive_id: String,
-
-        /// Skip confirmation prompt
-        #[arg(short = 'y', long)]
-        yes: bool,
-    },
-}
-
 fn main() {
     if let Err(_) = run() {
         std::process::exit(1);
@@ -725,10 +705,9 @@ fn run() -> Result<()> {
         Commands::Ui => unreachable!(), // Handled above
         Commands::Explore => commands::explore::run(&client),
 
-        // Health, Metrics, and Version
+        // Health and Metrics
         Commands::Health => commands::health::health(&client, verbose, output_format),
         Commands::Metrics => commands::health::metrics(&client, verbose, output_format),
-        Commands::Version => commands::health::version(&client, verbose, output_format),
 
         // Bank commands
         Commands::Bank(bank_cmd) => match bank_cmd {
@@ -754,12 +733,6 @@ fn run() -> Result<()> {
             BankCommands::Delete { bank_id, yes } => {
                 commands::bank::delete(&client, &bank_id, yes, verbose, output_format)
             }
-            BankCommands::Consolidate { bank_id } => {
-                commands::bank::consolidate(&client, &bank_id, verbose, output_format)
-            }
-            BankCommands::ClearObservations { bank_id, yes } => {
-                commands::bank::clear_observations(&client, &bank_id, yes, verbose, output_format)
-            }
         },
 
         // Memory commands
@@ -790,6 +763,37 @@ 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 } => {
@@ -842,47 +846,6 @@ fn run() -> Result<()> {
                 commands::operation::cancel(&client, &bank_id, &operation_id, verbose, output_format)
             }
         },
-
-        // Mental model commands
-        Commands::MentalModel(mm_cmd) => match mm_cmd {
-            MentalModelCommands::List { bank_id } => {
-                commands::mental_model::list(&client, &bank_id, verbose, output_format)
-            }
-            MentalModelCommands::Get { bank_id, mental_model_id } => {
-                commands::mental_model::get(&client, &bank_id, &mental_model_id, verbose, output_format)
-            }
-            MentalModelCommands::Create { bank_id, name, source_query } => {
-                commands::mental_model::create(&client, &bank_id, &name, &source_query, verbose, output_format)
-            }
-            MentalModelCommands::Update { bank_id, mental_model_id, name } => {
-                commands::mental_model::update(&client, &bank_id, &mental_model_id, name, verbose, output_format)
-            }
-            MentalModelCommands::Delete { bank_id, mental_model_id, yes } => {
-                commands::mental_model::delete(&client, &bank_id, &mental_model_id, yes, verbose, output_format)
-            }
-            MentalModelCommands::Refresh { bank_id, mental_model_id } => {
-                commands::mental_model::refresh(&client, &bank_id, &mental_model_id, verbose, output_format)
-            }
-        },
-
-        // Directive commands
-        Commands::Directive(dir_cmd) => match dir_cmd {
-            DirectiveCommands::List { bank_id } => {
-                commands::directive::list(&client, &bank_id, verbose, output_format)
-            }
-            DirectiveCommands::Get { bank_id, directive_id } => {
-                commands::directive::get(&client, &bank_id, &directive_id, verbose, output_format)
-            }
-            DirectiveCommands::Create { bank_id, name, content } => {
-                commands::directive::create(&client, &bank_id, &name, &content, verbose, output_format)
-            }
-            DirectiveCommands::Update { bank_id, directive_id, name, content } => {
-                commands::directive::update(&client, &bank_id, &directive_id, name, content, verbose, output_format)
-            }
-            DirectiveCommands::Delete { bank_id, directive_id, yes } => {
-                commands::directive::delete(&client, &bank_id, &directive_id, yes, verbose, output_format)
-            }
-        },
     };
 
     // Handle API errors with nice messages

hindsight-cli/src/ui.rs

@@ -173,7 +173,7 @@ pub fn print_think_response(response: &ReflectResponse) {
     println!();
 
     if let Some(based_on) = &response.based_on {
-        let count = based_on.memories.len();
+        let count = based_on.memories.len() + based_on.mental_models.len();
         if count > 0 {
             println!("{}", dim(&format!("Based on {} memory units", count)));
         }

hindsight-cli/tests/cli_integration.rs

@@ -481,409 +481,3 @@ fn test_json_yaml_output_formats() {
             .expect("Expected valid YAML for bank list");
     }
 }
-
-// ============================================================================
-// Directive Tests
-// ============================================================================
-
-#[test]
-fn test_directive_list() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("dir-list");
-
-    // Create the bank first
-    let _ = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    // List directives
-    let output = run_hindsight(&["directive", "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(),
-        "Directive list command failed: {} / {}",
-        stdout,
-        stderr
-    );
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_directive_create_get_update_delete() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("dir-crud");
-
-    // Create the bank first
-    let _ = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    // Create a directive
-    let output = run_hindsight(&[
-        "directive", "create",
-        &bank_id,
-        "Test Directive",
-        "Always respond politely",
-    ]);
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    assert!(
-        output.status.success(),
-        "Directive create failed: stdout={}, stderr={}",
-        stdout,
-        stderr
-    );
-
-    // List directives and get the ID
-    let output = run_hindsight(&["directive", "list", &bank_id, "-o", "json"]);
-    let stdout = String::from_utf8_lossy(&output.stdout);
-
-    assert!(
-        output.status.success(),
-        "Directive list failed: {}",
-        stdout
-    );
-
-    // Parse JSON and get directive ID
-    let directive_id: Option<String> = if let Ok(result) = serde_json::from_str::<serde_json::Value>(&stdout) {
-        result.get("items")
-            .and_then(|v| v.as_array())
-            .and_then(|items| items.first())
-            .and_then(|item| item.get("id"))
-            .and_then(|v| v.as_str())
-            .map(|s| s.to_string())
-    } else {
-        None
-    };
-
-    if let Some(id) = directive_id {
-        // Get the directive
-        let output = run_hindsight(&["directive", "get", &bank_id, &id]);
-        let stdout = String::from_utf8_lossy(&output.stdout);
-        let stderr = String::from_utf8_lossy(&output.stderr);
-
-        assert!(
-            output.status.success(),
-            "Directive get failed: stdout={}, stderr={}",
-            stdout,
-            stderr
-        );
-
-        // Update the directive
-        let output = run_hindsight(&[
-            "directive", "update",
-            &bank_id,
-            &id,
-            "--name", "Updated Directive",
-            "--content", "Always respond very politely",
-        ]);
-        let stdout = String::from_utf8_lossy(&output.stdout);
-        let stderr = String::from_utf8_lossy(&output.stderr);
-
-        assert!(
-            output.status.success(),
-            "Directive update failed: stdout={}, stderr={}",
-            stdout,
-            stderr
-        );
-
-        // Verify update in JSON
-        let output = run_hindsight(&["directive", "get", &bank_id, &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 Directive")
-            );
-        }
-
-        // Delete the directive
-        let output = run_hindsight(&["directive", "delete", &bank_id, &id, "-y"]);
-        let stdout = String::from_utf8_lossy(&output.stdout);
-        let stderr = String::from_utf8_lossy(&output.stderr);
-
-        assert!(
-            output.status.success(),
-            "Directive delete failed: stdout={}, stderr={}",
-            stdout,
-            stderr
-        );
-    }
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-// ============================================================================
-// Mental Model Extended Tests
-// ============================================================================
-
-#[test]
-fn test_mental_model_get() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("mm-get");
-
-    // 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 Get Model",
-        "What are the key facts?",
-    ]);
-
-    if output.status.success() {
-        // List to get the ID
-        let output = run_hindsight(&["mental-model", "list", &bank_id, "-o", "json"]);
-        let stdout = String::from_utf8_lossy(&output.stdout);
-
-        if let Ok(result) = serde_json::from_str::<serde_json::Value>(&stdout) {
-            if let Some(id) = result.get("items")
-                .and_then(|v| v.as_array())
-                .and_then(|items| items.iter().find(|item| {
-                    item.get("name").and_then(|v| v.as_str()) == Some("Test Get Model")
-                }))
-                .and_then(|item| item.get("id"))
-                .and_then(|v| v.as_str())
-            {
-                // Get the mental model
-                let output = run_hindsight(&["mental-model", "get", &bank_id, id]);
-                let stdout = String::from_utf8_lossy(&output.stdout);
-                let stderr = String::from_utf8_lossy(&output.stderr);
-
-                assert!(
-                    output.status.success(),
-                    "Mental model get failed: stdout={}, stderr={}",
-                    stdout,
-                    stderr
-                );
-            }
-        }
-    }
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_mental_model_update() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("mm-update");
-
-    // 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 Update Model",
-        "What are the key facts?",
-    ]);
-
-    if output.status.success() {
-        // List to get the ID
-        let output = run_hindsight(&["mental-model", "list", &bank_id, "-o", "json"]);
-        let stdout = String::from_utf8_lossy(&output.stdout);
-
-        if let Ok(result) = serde_json::from_str::<serde_json::Value>(&stdout) {
-            if let Some(id) = result.get("items")
-                .and_then(|v| v.as_array())
-                .and_then(|items| items.iter().find(|item| {
-                    item.get("name").and_then(|v| v.as_str()) == Some("Test Update Model")
-                }))
-                .and_then(|item| item.get("id"))
-                .and_then(|v| v.as_str())
-            {
-                // Update the mental model
-                let output = run_hindsight(&[
-                    "mental-model", "update",
-                    &bank_id,
-                    id,
-                    "--name", "Updated Model Name",
-                ]);
-                let stdout = String::from_utf8_lossy(&output.stdout);
-                let stderr = String::from_utf8_lossy(&output.stderr);
-
-                assert!(
-                    output.status.success(),
-                    "Mental model update failed: stdout={}, stderr={}",
-                    stdout,
-                    stderr
-                );
-
-                // Verify update
-                let output = run_hindsight(&["mental-model", "get", &bank_id, 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 Model Name")
-                    );
-                }
-            }
-        }
-    }
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_mental_model_refresh() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("mm-refresh");
-
-    // 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 Refresh Model",
-        "What are the key facts?",
-    ]);
-
-    if output.status.success() {
-        // List to get the ID
-        let output = run_hindsight(&["mental-model", "list", &bank_id, "-o", "json"]);
-        let stdout = String::from_utf8_lossy(&output.stdout);
-
-        if let Ok(result) = serde_json::from_str::<serde_json::Value>(&stdout) {
-            if let Some(id) = result.get("items")
-                .and_then(|v| v.as_array())
-                .and_then(|items| items.iter().find(|item| {
-                    item.get("name").and_then(|v| v.as_str()) == Some("Test Refresh Model")
-                }))
-                .and_then(|item| item.get("id"))
-                .and_then(|v| v.as_str())
-            {
-                // Refresh the mental model
-                let output = run_hindsight(&["mental-model", "refresh", &bank_id, id]);
-                let stdout = String::from_utf8_lossy(&output.stdout);
-                let stderr = String::from_utf8_lossy(&output.stderr);
-
-                assert!(
-                    output.status.success(),
-                    "Mental model refresh failed: stdout={}, stderr={}",
-                    stdout,
-                    stderr
-                );
-            }
-        }
-    }
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-// ============================================================================
-// Bank Consolidation Tests
-// ============================================================================
-
-#[test]
-fn test_bank_consolidate() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("bank-consolidate");
-
-    // Create the bank first
-    let _ = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    // Trigger consolidation
-    let output = run_hindsight(&["bank", "consolidate", &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 consolidate command failed: {} / {}",
-        stdout,
-        stderr
-    );
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-#[test]
-fn test_bank_clear_observations() {
-    skip_if_no_server!();
-
-    let bank_id = test_bank_id("bank-clear-obs");
-
-    // Create the bank first
-    let _ = run_hindsight(&["bank", "create", &bank_id, "--name", "Test Bank"]);
-
-    // Clear observations
-    let output = run_hindsight(&["bank", "clear-observations", &bank_id, "-y"]);
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // Should succeed
-    assert!(
-        output.status.success(),
-        "Bank clear-observations command failed: {} / {}",
-        stdout,
-        stderr
-    );
-
-    // Clean up
-    let _ = run_hindsight(&["bank", "delete", &bank_id, "-y"]);
-}
-
-// ============================================================================
-// Version Test
-// ============================================================================
-
-#[test]
-fn test_version() {
-    skip_if_no_server!();
-
-    let output = run_hindsight(&["version"]);
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // Should succeed
-    assert!(
-        output.status.success(),
-        "Version command failed: {} / {}",
-        stdout,
-        stderr
-    );
-}
-
-#[test]
-fn test_version_json() {
-    skip_if_no_server!();
-
-    let output = run_hindsight(&["version", "-o", "json"]);
-
-    if output.status.success() {
-        let stdout = String::from_utf8_lossy(&output.stdout);
-        let result: serde_json::Value = serde_json::from_str(&stdout)
-            .expect(&format!("Expected valid JSON output, got: {}", stdout));
-
-        // Should have api_version and features
-        assert!(result.get("api_version").is_some(), "Expected api_version field");
-        assert!(result.get("features").is_some(), "Expected features field");
-    }
-}

hindsight-clients/python/.openapi-generator/FILES

@@ -1,7 +1,6 @@
 hindsight_client_api/__init__.py
 hindsight_client_api/api/__init__.py
 hindsight_client_api/api/banks_api.py
-hindsight_client_api/api/directives_api.py
 hindsight_client_api/api/documents_api.py
 hindsight_client_api/api/entities_api.py
 hindsight_client_api/api/memory_api.py
@@ -25,15 +24,11 @@ hindsight_client_api/models/cancel_operation_response.py
 hindsight_client_api/models/chunk_data.py
 hindsight_client_api/models/chunk_include_options.py
 hindsight_client_api/models/chunk_response.py
-hindsight_client_api/models/consolidation_response.py
 hindsight_client_api/models/create_bank_request.py
-hindsight_client_api/models/create_directive_request.py
 hindsight_client_api/models/create_mental_model_request.py
-hindsight_client_api/models/create_mental_model_response.py
+hindsight_client_api/models/created_mental_model.py
 hindsight_client_api/models/delete_document_response.py
 hindsight_client_api/models/delete_response.py
-hindsight_client_api/models/directive_list_response.py
-hindsight_client_api/models/directive_response.py
 hindsight_client_api/models/disposition_traits.py
 hindsight_client_api/models/document_response.py
 hindsight_client_api/models/entity_detail_response.py
@@ -43,7 +38,6 @@ hindsight_client_api/models/entity_list_item.py
 hindsight_client_api/models/entity_list_response.py
 hindsight_client_api/models/entity_observation_response.py
 hindsight_client_api/models/entity_state_response.py
-hindsight_client_api/models/features_info.py
 hindsight_client_api/models/graph_data_response.py
 hindsight_client_api/models/http_validation_error.py
 hindsight_client_api/models/include_options.py
@@ -51,9 +45,12 @@ hindsight_client_api/models/list_documents_response.py
 hindsight_client_api/models/list_memory_units_response.py
 hindsight_client_api/models/list_tags_response.py
 hindsight_client_api/models/memory_item.py
+hindsight_client_api/models/mental_model_freshness_response.py
 hindsight_client_api/models/mental_model_list_response.py
+hindsight_client_api/models/mental_model_observation_response.py
 hindsight_client_api/models/mental_model_response.py
-hindsight_client_api/models/mental_model_trigger.py
+hindsight_client_api/models/observation_evidence_response.py
+hindsight_client_api/models/observation_input.py
 hindsight_client_api/models/operation_response.py
 hindsight_client_api/models/operation_status_response.py
 hindsight_client_api/models/operations_list_response.py
@@ -61,7 +58,6 @@ hindsight_client_api/models/recall_request.py
 hindsight_client_api/models/recall_response.py
 hindsight_client_api/models/recall_result.py
 hindsight_client_api/models/reflect_based_on.py
-hindsight_client_api/models/reflect_directive.py
 hindsight_client_api/models/reflect_fact.py
 hindsight_client_api/models/reflect_include_options.py
 hindsight_client_api/models/reflect_llm_call.py
@@ -70,16 +66,15 @@ hindsight_client_api/models/reflect_request.py
 hindsight_client_api/models/reflect_response.py
 hindsight_client_api/models/reflect_tool_call.py
 hindsight_client_api/models/reflect_trace.py
+hindsight_client_api/models/refresh_mental_models_request.py
 hindsight_client_api/models/retain_request.py
 hindsight_client_api/models/retain_response.py
 hindsight_client_api/models/tag_item.py
 hindsight_client_api/models/token_usage.py
 hindsight_client_api/models/tool_calls_include_options.py
-hindsight_client_api/models/update_directive_request.py
 hindsight_client_api/models/update_disposition_request.py
 hindsight_client_api/models/update_mental_model_request.py
 hindsight_client_api/models/validation_error.py
 hindsight_client_api/models/validation_error_loc_inner.py
-hindsight_client_api/models/version_response.py
 hindsight_client_api/rest.py
 hindsight_client_api_README.md

hindsight-clients/python/hindsight_client/__init__.py

@@ -25,18 +25,17 @@ Example:
     ```
 """
 
-from hindsight_client_api.models.bank_profile_response import BankProfileResponse
-from hindsight_client_api.models.disposition_traits import DispositionTraits
-from hindsight_client_api.models.list_memory_units_response import ListMemoryUnitsResponse
-from hindsight_client_api.models.recall_response import RecallResponse as _RecallResponse
-from hindsight_client_api.models.recall_result import RecallResult as _RecallResult
-from hindsight_client_api.models.reflect_fact import ReflectFact
-from hindsight_client_api.models.reflect_response import ReflectResponse
+from .hindsight_client import Hindsight
 
 # Re-export response types for convenient access
 from hindsight_client_api.models.retain_response import RetainResponse
-
-from .hindsight_client import Hindsight
+from hindsight_client_api.models.recall_response import RecallResponse as _RecallResponse
+from hindsight_client_api.models.recall_result import RecallResult as _RecallResult
+from hindsight_client_api.models.reflect_response import ReflectResponse
+from hindsight_client_api.models.reflect_fact import ReflectFact
+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.disposition_traits import DispositionTraits
 
 
 # Add cleaner __repr__ and __iter__ for REPL usability

hindsight-clients/python/hindsight_client/hindsight_client.py

@@ -6,23 +6,26 @@ easy-to-use interface on top of the auto-generated OpenAPI client.
 """
 
 import asyncio
+from typing import Optional, List, Dict, Any, Literal
 from datetime import datetime
-from typing import Any, Literal
 
 import hindsight_client_api
-from hindsight_client_api.api import banks_api, directives_api, memory_api, mental_models_api
+from hindsight_client_api.api import memory_api, banks_api, mental_models_api
 from hindsight_client_api.models import (
-    memory_item,
     recall_request,
-    reflect_request,
     retain_request,
+    memory_item,
+    reflect_request,
 )
-from hindsight_client_api.models.bank_profile_response import BankProfileResponse
-from hindsight_client_api.models.list_memory_units_response import ListMemoryUnitsResponse
+from hindsight_client_api.models.retain_response import RetainResponse
 from hindsight_client_api.models.recall_response import RecallResponse
 from hindsight_client_api.models.recall_result import RecallResult
 from hindsight_client_api.models.reflect_response import ReflectResponse
-from hindsight_client_api.models.retain_response import RetainResponse
+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):
@@ -63,7 +66,7 @@ class Hindsight:
         ```
     """
 
-    def __init__(self, base_url: str, api_key: str | None = None, timeout: float = 30.0):
+    def __init__(self, base_url: str, api_key: Optional[str] = None, timeout: float = 30.0):
         """
         Initialize the Hindsight client.
 
@@ -79,7 +82,6 @@ class Hindsight:
         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)
-        self._directives_api = directives_api.DirectivesApi(self._api_client)
 
     def __enter__(self):
         """Context manager entry."""
@@ -112,12 +114,12 @@ class Hindsight:
         self,
         bank_id: str,
         content: str,
-        timestamp: datetime | None = None,
-        context: str | None = None,
-        document_id: str | None = None,
-        metadata: dict[str, str] | None = None,
-        entities: list[dict[str, str]] | None = None,
-        tags: list[str] | None = None,
+        timestamp: Optional[datetime] = None,
+        context: Optional[str] = None,
+        document_id: Optional[str] = None,
+        metadata: Optional[Dict[str, str]] = None,
+        entities: Optional[List[Dict[str, str]]] = None,
+        tags: Optional[List[str]] = None,
     ) -> RetainResponse:
         """
         Store a single memory (simplified interface).
@@ -130,33 +132,24 @@ class Hindsight:
             document_id: Optional document ID for grouping
             metadata: Optional user-defined metadata
             entities: Optional list of entities [{"text": "...", "type": "..."}]
-            tags: Optional list of tags for filtering memories during recall/reflect
+            tags: Optional list of tags for this memory
 
         Returns:
             RetainResponse with success status
         """
         return self.retain_batch(
             bank_id=bank_id,
-            items=[
-                {
-                    "content": content,
-                    "timestamp": timestamp,
-                    "context": context,
-                    "metadata": metadata,
-                    "entities": entities,
-                    "tags": tags,
-                }
-            ],
+            items=[{"content": content, "timestamp": timestamp, "context": context, "metadata": metadata, "entities": entities, "tags": tags}],
             document_id=document_id,
         )
 
     def retain_batch(
         self,
         bank_id: str,
-        items: list[dict[str, Any]],
-        document_id: str | None = None,
-        document_tags: list[str] | None = None,
+        items: List[Dict[str, Any]],
+        document_id: Optional[str] = None,
         retain_async: bool = False,
+        document_tags: Optional[List[str]] = None,
     ) -> RetainResponse:
         """
         Store multiple memories in batch.
@@ -165,8 +158,8 @@ class Hindsight:
             bank_id: The memory bank ID
             items: List of memory items with 'content' and optional 'timestamp', 'context', 'metadata', 'document_id', 'entities', 'tags'
             document_id: Optional document ID for grouping memories (applied to items that don't have their own)
-            document_tags: Optional list of tags applied to all items in this batch (merged with per-item tags)
             retain_async: If True, process asynchronously in background (default: False)
+            document_tags: Optional list of tags to apply to all memories in this batch
 
         Returns:
             RetainResponse with success status and item count
@@ -177,7 +170,10 @@ class Hindsight:
         for item in items:
             entities = None
             if item.get("entities"):
-                entities = [EntityInput(text=e["text"], type=e.get("type")) for e in item["entities"]]
+                entities = [
+                    EntityInput(text=e["text"], type=e.get("type"))
+                    for e in item["entities"]
+                ]
             memory_items.append(
                 memory_item.MemoryItem(
                     content=item["content"],
@@ -203,17 +199,17 @@ class Hindsight:
         self,
         bank_id: str,
         query: str,
-        types: list[str] | None = None,
+        types: Optional[List[str]] = None,
         max_tokens: int = 4096,
         budget: str = "mid",
         trace: bool = False,
-        query_timestamp: str | None = None,
+        query_timestamp: Optional[str] = None,
         include_entities: bool = False,
         max_entity_tokens: int = 500,
         include_chunks: bool = False,
         max_chunk_tokens: int = 8192,
-        tags: list[str] | None = None,
-        tags_match: Literal["any", "all", "any_strict", "all_strict"] = "any",
+        tags: Optional[List[str]] = None,
+        tags_match: str = "any",
     ) -> RecallResponse:
         """
         Recall memories using semantic similarity.
@@ -231,18 +227,16 @@ class Hindsight:
             include_chunks: Include raw text chunks in results (default: False)
             max_chunk_tokens: Maximum tokens for chunks (default: 8192)
             tags: Optional list of tags to filter memories by
-            tags_match: How to match tags - "any" (OR, includes untagged), "all" (AND, includes untagged),
-                "any_strict" (OR, excludes untagged), "all_strict" (AND, excludes untagged). Default: "any"
+            tags_match: How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged),
+                'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged). Default: 'any'
 
         Returns:
             RecallResponse with results, optional entities, optional chunks, and optional trace
         """
-        from hindsight_client_api.models import chunk_include_options, entity_include_options, include_options
+        from hindsight_client_api.models import include_options, entity_include_options, chunk_include_options
 
         include_opts = include_options.IncludeOptions(
-            entities=entity_include_options.EntityIncludeOptions(max_tokens=max_entity_tokens)
-            if include_entities
-            else None,
+            entities=entity_include_options.EntityIncludeOptions(max_tokens=max_entity_tokens) if include_entities else None,
             chunks=chunk_include_options.ChunkIncludeOptions(max_tokens=max_chunk_tokens) if include_chunks else None,
         )
 
@@ -265,11 +259,11 @@ class Hindsight:
         bank_id: str,
         query: str,
         budget: str = "low",
-        context: str | None = None,
-        max_tokens: int | None = None,
-        response_schema: dict[str, Any] | None = None,
-        tags: list[str] | None = None,
-        tags_match: Literal["any", "all", "any_strict", "all_strict"] = "any",
+        context: Optional[str] = None,
+        max_tokens: Optional[int] = None,
+        response_schema: Optional[Dict[str, Any]] = None,
+        tags: Optional[List[str]] = None,
+        tags_match: str = "any",
     ) -> ReflectResponse:
         """
         Generate a contextual answer based on bank identity and memories.
@@ -284,8 +278,8 @@ class Hindsight:
                 the response will include a 'structured_output' field with the LLM
                 response parsed according to this schema.
             tags: Optional list of tags to filter memories by
-            tags_match: How to match tags - "any" (OR, includes untagged), "all" (AND, includes untagged),
-                "any_strict" (OR, excludes untagged), "all_strict" (AND, excludes untagged). Default: "any"
+            tags_match: How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged),
+                'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged). Default: 'any'
 
         Returns:
             ReflectResponse with answer text, optionally facts used, and optionally
@@ -306,37 +300,28 @@ class Hindsight:
     def list_memories(
         self,
         bank_id: str,
-        type: str | None = None,
-        search_query: str | None = None,
+        type: Optional[str] = None,
+        search_query: Optional[str] = None,
         limit: int = 100,
         offset: int = 0,
     ) -> ListMemoryUnitsResponse:
         """List memory units with pagination."""
-        return _run_async(
-            self._memory_api.list_memories(
-                bank_id=bank_id,
-                type=type,
-                q=search_query,
-                limit=limit,
-                offset=offset,
-            )
-        )
+        return _run_async(self._memory_api.list_memories(
+            bank_id=bank_id,
+            type=type,
+            q=search_query,
+            limit=limit,
+            offset=offset,
+        ))
 
     def create_bank(
         self,
         bank_id: str,
-        name: str | None = None,
-        mission: str | None = None,
-        disposition: dict[str, float] | None = None,
+        name: Optional[str] = None,
+        background: Optional[str] = None,
+        disposition: Optional[Dict[str, float]] = None,
     ) -> BankProfileResponse:
-        """Create or update a memory bank.
-
-        Args:
-            bank_id: Unique identifier for the bank
-            name: Human-readable display name
-            mission: Instructions guiding what Hindsight should learn and remember (for mental models)
-            disposition: Optional disposition traits (skepticism, literalism, empathy)
-        """
+        """Create or update a memory bank."""
         from hindsight_client_api.models import create_bank_request, disposition_traits
 
         disposition_obj = None
@@ -345,7 +330,7 @@ class Hindsight:
 
         request_obj = create_bank_request.CreateBankRequest(
             name=name,
-            mission=mission,
+            background=background,
             disposition=disposition_obj,
         )
 
@@ -371,14 +356,243 @@ class Hindsight:
         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(
         self,
         bank_id: str,
-        items: list[dict[str, Any]],
-        document_id: str | None = None,
-        document_tags: list[str] | None = None,
+        items: List[Dict[str, Any]],
+        document_id: Optional[str] = None,
         retain_async: bool = False,
     ) -> RetainResponse:
         """
@@ -386,9 +600,8 @@ class Hindsight:
 
         Args:
             bank_id: The memory bank ID
-            items: List of memory items with 'content' and optional 'timestamp', 'context', 'metadata', 'document_id', 'entities', 'tags'
+            items: List of memory items with 'content' and optional 'timestamp', 'context', 'metadata', 'document_id', 'entities'
             document_id: Optional document ID for grouping memories (applied to items that don't have their own)
-            document_tags: Optional list of tags applied to all items in this batch (merged with per-item tags)
             retain_async: If True, process asynchronously in background (default: False)
 
         Returns:
@@ -400,7 +613,10 @@ class Hindsight:
         for item in items:
             entities = None
             if item.get("entities"):
-                entities = [EntityInput(text=e["text"], type=e.get("type")) for e in item["entities"]]
+                entities = [
+                    EntityInput(text=e["text"], type=e.get("type"))
+                    for e in item["entities"]
+                ]
             memory_items.append(
                 memory_item.MemoryItem(
                     content=item["content"],
@@ -410,14 +626,12 @@ class Hindsight:
                     # Use item's document_id if provided, otherwise fall back to batch-level document_id
                     document_id=item.get("document_id") or document_id,
                     entities=entities,
-                    tags=item.get("tags"),
                 )
             )
 
         request_obj = retain_request.RetainRequest(
             items=memory_items,
             async_=retain_async,
-            document_tags=document_tags,
         )
 
         return await self._memory_api.retain_memories(bank_id, request_obj)
@@ -426,12 +640,11 @@ class Hindsight:
         self,
         bank_id: str,
         content: str,
-        timestamp: datetime | None = None,
-        context: str | None = None,
-        document_id: str | None = None,
-        metadata: dict[str, str] | None = None,
-        entities: list[dict[str, str]] | None = None,
-        tags: list[str] | None = None,
+        timestamp: Optional[datetime] = None,
+        context: Optional[str] = None,
+        document_id: Optional[str] = None,
+        metadata: Optional[Dict[str, str]] = None,
+        entities: Optional[List[Dict[str, str]]] = None,
     ) -> RetainResponse:
         """
         Store a single memory (async).
@@ -444,23 +657,13 @@ class Hindsight:
             document_id: Optional document ID for grouping
             metadata: Optional user-defined metadata
             entities: Optional list of entities [{"text": "...", "type": "..."}]
-            tags: Optional list of tags for filtering memories during recall/reflect
 
         Returns:
             RetainResponse with success status
         """
         return await self.aretain_batch(
             bank_id=bank_id,
-            items=[
-                {
-                    "content": content,
-                    "timestamp": timestamp,
-                    "context": context,
-                    "metadata": metadata,
-                    "entities": entities,
-                    "tags": tags,
-                }
-            ],
+            items=[{"content": content, "timestamp": timestamp, "context": context, "metadata": metadata, "entities": entities}],
             document_id=document_id,
         )
 
@@ -468,12 +671,10 @@ class Hindsight:
         self,
         bank_id: str,
         query: str,
-        types: list[str] | None = None,
+        types: Optional[List[str]] = None,
         max_tokens: int = 4096,
         budget: str = "mid",
-        tags: list[str] | None = None,
-        tags_match: Literal["any", "all", "any_strict", "all_strict"] = "any",
-    ) -> list[RecallResult]:
+    ) -> List[RecallResult]:
         """
         Recall memories using semantic similarity (async).
 
@@ -483,9 +684,6 @@ class Hindsight:
             types: Optional list of fact types to filter (world, experience, opinion, observation)
             max_tokens: Maximum tokens in results (default: 4096)
             budget: Budget level for recall - "low", "mid", or "high" (default: "mid")
-            tags: Optional list of tags to filter memories by
-            tags_match: How to match tags - "any" (OR, includes untagged), "all" (AND, includes untagged),
-                "any_strict" (OR, excludes untagged), "all_strict" (AND, excludes untagged). Default: "any"
 
         Returns:
             List of RecallResult objects
@@ -496,21 +694,17 @@ class Hindsight:
             budget=budget,
             max_tokens=max_tokens,
             trace=False,
-            tags=tags,
-            tags_match=tags_match,
         )
 
         response = await self._memory_api.recall_memories(bank_id, request_obj)
-        return response.results if hasattr(response, "results") else []
+        return response.results if hasattr(response, 'results') else []
 
     async def areflect(
         self,
         bank_id: str,
         query: str,
         budget: str = "low",
-        context: str | None = None,
-        tags: list[str] | None = None,
-        tags_match: Literal["any", "all", "any_strict", "all_strict"] = "any",
+        context: Optional[str] = None,
     ) -> ReflectResponse:
         """
         Generate a contextual answer based on bank identity and memories (async).
@@ -520,9 +714,6 @@ class Hindsight:
             query: The question or prompt
             budget: Budget level for reflection - "low", "mid", or "high" (default: "low")
             context: Optional additional context
-            tags: Optional list of tags to filter memories by
-            tags_match: How to match tags - "any" (OR, includes untagged), "all" (AND, includes untagged),
-                "any_strict" (OR, excludes untagged), "all_strict" (AND, excludes untagged). Default: "any"
 
         Returns:
             ReflectResponse with answer text and optionally facts used
@@ -531,258 +722,6 @@ class Hindsight:
             query=query,
             budget=budget,
             context=context,
-            tags=tags,
-            tags_match=tags_match,
         )
 
         return await self._memory_api.reflect(bank_id, request_obj)
-
-    # Mental Models methods
-
-    def create_mental_model(
-        self,
-        bank_id: str,
-        name: str,
-        source_query: str,
-        tags: list[str] | None = None,
-        max_tokens: int | None = None,
-        trigger: dict[str, Any] | None = None,
-    ):
-        """
-        Create a mental model (runs reflect in background).
-
-        Args:
-            bank_id: The memory bank ID
-            name: Human-readable name for the mental model
-            source_query: The query to run to generate content
-            tags: Optional tags for filtering during retrieval
-            max_tokens: Optional maximum tokens for the mental model content
-            trigger: Optional trigger settings (e.g., {"refresh_after_consolidation": True})
-
-        Returns:
-            CreateMentalModelResponse with operation_id
-        """
-        from hindsight_client_api.models import create_mental_model_request, mental_model_trigger
-
-        trigger_obj = None
-        if trigger:
-            trigger_obj = mental_model_trigger.MentalModelTrigger(**trigger)
-
-        request_obj = create_mental_model_request.CreateMentalModelRequest(
-            name=name,
-            source_query=source_query,
-            tags=tags,
-            max_tokens=max_tokens,
-            trigger=trigger_obj,
-        )
-
-        return _run_async(self._mental_models_api.create_mental_model(bank_id, request_obj))
-
-    def list_mental_models(self, bank_id: str, tags: list[str] | None = None):
-        """
-        List all mental models in a bank.
-
-        Args:
-            bank_id: The memory bank ID
-            tags: Optional tags to filter by
-
-        Returns:
-            ListMentalModelsResponse with items
-        """
-        return _run_async(self._mental_models_api.list_mental_models(bank_id, tags=tags))
-
-    def get_mental_model(self, bank_id: str, mental_model_id: str):
-        """
-        Get a specific mental model.
-
-        Args:
-            bank_id: The memory bank ID
-            mental_model_id: The mental model ID
-
-        Returns:
-            MentalModelResponse
-        """
-        return _run_async(self._mental_models_api.get_mental_model(bank_id, mental_model_id))
-
-    def refresh_mental_model(self, bank_id: str, mental_model_id: str):
-        """
-        Refresh a mental model to update with current knowledge.
-
-        Args:
-            bank_id: The memory bank ID
-            mental_model_id: The mental model ID
-
-        Returns:
-            RefreshMentalModelResponse with operation_id
-        """
-        return _run_async(self._mental_models_api.refresh_mental_model(bank_id, mental_model_id))
-
-    def update_mental_model(
-        self,
-        bank_id: str,
-        mental_model_id: str,
-        name: str | None = None,
-        source_query: str | None = None,
-        tags: list[str] | None = None,
-        max_tokens: int | None = None,
-        trigger: dict[str, Any] | None = None,
-    ):
-        """
-        Update a mental model's metadata.
-
-        Args:
-            bank_id: The memory bank ID
-            mental_model_id: The mental model ID
-            name: Optional new name
-            source_query: Optional new source query
-            tags: Optional new tags
-            max_tokens: Optional new max tokens
-            trigger: Optional trigger settings (e.g., {"refresh_after_consolidation": True})
-
-        Returns:
-            MentalModelResponse
-        """
-        from hindsight_client_api.models import mental_model_trigger, update_mental_model_request
-
-        trigger_obj = None
-        if trigger:
-            trigger_obj = mental_model_trigger.MentalModelTrigger(**trigger)
-
-        request_obj = update_mental_model_request.UpdateMentalModelRequest(
-            name=name,
-            source_query=source_query,
-            tags=tags,
-            max_tokens=max_tokens,
-            trigger=trigger_obj,
-        )
-
-        return _run_async(self._mental_models_api.update_mental_model(bank_id, mental_model_id, request_obj))
-
-    def delete_mental_model(self, bank_id: str, mental_model_id: str):
-        """
-        Delete a mental model.
-
-        Args:
-            bank_id: The memory bank ID
-            mental_model_id: The mental model ID
-        """
-        return _run_async(self._mental_models_api.delete_mental_model(bank_id, mental_model_id))
-
-    # Directives methods
-
-    def create_directive(
-        self,
-        bank_id: str,
-        name: str,
-        content: str,
-        priority: int = 0,
-        is_active: bool = True,
-        tags: list[str] | None = None,
-    ):
-        """
-        Create a directive (hard rule for reflect).
-
-        Args:
-            bank_id: The memory bank ID
-            name: Human-readable name for the directive
-            content: The directive content/rules
-            priority: Priority level (higher = injected first)
-            is_active: Whether the directive is active
-            tags: Optional tags for filtering
-
-        Returns:
-            DirectiveResponse
-        """
-        from hindsight_client_api.models import create_directive_request
-
-        request_obj = create_directive_request.CreateDirectiveRequest(
-            name=name,
-            content=content,
-            priority=priority,
-            is_active=is_active,
-            tags=tags,
-        )
-
-        return _run_async(self._directives_api.create_directive(bank_id, request_obj))
-
-    def list_directives(self, bank_id: str, tags: list[str] | None = None):
-        """
-        List all directives in a bank.
-
-        Args:
-            bank_id: The memory bank ID
-            tags: Optional tags to filter by
-
-        Returns:
-            ListDirectivesResponse with items
-        """
-        return _run_async(self._directives_api.list_directives(bank_id, tags=tags))
-
-    def get_directive(self, bank_id: str, directive_id: str):
-        """
-        Get a specific directive.
-
-        Args:
-            bank_id: The memory bank ID
-            directive_id: The directive ID
-
-        Returns:
-            DirectiveResponse
-        """
-        return _run_async(self._directives_api.get_directive(bank_id, directive_id))
-
-    def update_directive(
-        self,
-        bank_id: str,
-        directive_id: str,
-        name: str | None = None,
-        content: str | None = None,
-        priority: int | None = None,
-        is_active: bool | None = None,
-        tags: list[str] | None = None,
-    ):
-        """
-        Update a directive.
-
-        Args:
-            bank_id: The memory bank ID
-            directive_id: The directive ID
-            name: Optional new name
-            content: Optional new content
-            priority: Optional new priority
-            is_active: Optional new active status
-            tags: Optional new tags
-
-        Returns:
-            DirectiveResponse
-        """
-        from hindsight_client_api.models import update_directive_request
-
-        request_obj = update_directive_request.UpdateDirectiveRequest(
-            name=name,
-            content=content,
-            priority=priority,
-            is_active=is_active,
-            tags=tags,
-        )
-
-        return _run_async(self._directives_api.update_directive(bank_id, directive_id, request_obj))
-
-    def delete_directive(self, bank_id: str, directive_id: str):
-        """
-        Delete a directive.
-
-        Args:
-            bank_id: The memory bank ID
-            directive_id: The directive ID
-        """
-        return _run_async(self._directives_api.delete_directive(bank_id, directive_id))
-
-    def delete_bank(self, bank_id: str):
-        """
-        Delete a memory bank.
-
-        Args:
-            bank_id: The memory bank ID
-        """
-        return _run_async(self._banks_api.delete_bank(bank_id))

hindsight-clients/python/hindsight_client_api/__init__.py

@@ -18,7 +18,6 @@ __version__ = "0.0.7"
 
 # import apis into sdk package
 from hindsight_client_api.api.banks_api import BanksApi
-from hindsight_client_api.api.directives_api import DirectivesApi
 from hindsight_client_api.api.documents_api import DocumentsApi
 from hindsight_client_api.api.entities_api import EntitiesApi
 from hindsight_client_api.api.memory_api import MemoryApi
@@ -50,15 +49,11 @@ from hindsight_client_api.models.cancel_operation_response import CancelOperatio
 from hindsight_client_api.models.chunk_data import ChunkData
 from hindsight_client_api.models.chunk_include_options import ChunkIncludeOptions
 from hindsight_client_api.models.chunk_response import ChunkResponse
-from hindsight_client_api.models.consolidation_response import ConsolidationResponse
 from hindsight_client_api.models.create_bank_request import CreateBankRequest
-from hindsight_client_api.models.create_directive_request import CreateDirectiveRequest
 from hindsight_client_api.models.create_mental_model_request import CreateMentalModelRequest
-from hindsight_client_api.models.create_mental_model_response import CreateMentalModelResponse
+from hindsight_client_api.models.created_mental_model import CreatedMentalModel
 from hindsight_client_api.models.delete_document_response import DeleteDocumentResponse
 from hindsight_client_api.models.delete_response import DeleteResponse
-from hindsight_client_api.models.directive_list_response import DirectiveListResponse
-from hindsight_client_api.models.directive_response import DirectiveResponse
 from hindsight_client_api.models.disposition_traits import DispositionTraits
 from hindsight_client_api.models.document_response import DocumentResponse
 from hindsight_client_api.models.entity_detail_response import EntityDetailResponse
@@ -68,7 +63,6 @@ from hindsight_client_api.models.entity_list_item import EntityListItem
 from hindsight_client_api.models.entity_list_response import EntityListResponse
 from hindsight_client_api.models.entity_observation_response import EntityObservationResponse
 from hindsight_client_api.models.entity_state_response import EntityStateResponse
-from hindsight_client_api.models.features_info import FeaturesInfo
 from hindsight_client_api.models.graph_data_response import GraphDataResponse
 from hindsight_client_api.models.http_validation_error import HTTPValidationError
 from hindsight_client_api.models.include_options import IncludeOptions
@@ -76,9 +70,12 @@ from hindsight_client_api.models.list_documents_response import ListDocumentsRes
 from hindsight_client_api.models.list_memory_units_response import ListMemoryUnitsResponse
 from hindsight_client_api.models.list_tags_response import ListTagsResponse
 from hindsight_client_api.models.memory_item import MemoryItem
+from hindsight_client_api.models.mental_model_freshness_response import MentalModelFreshnessResponse
 from hindsight_client_api.models.mental_model_list_response import MentalModelListResponse
+from hindsight_client_api.models.mental_model_observation_response import MentalModelObservationResponse
 from hindsight_client_api.models.mental_model_response import MentalModelResponse
-from hindsight_client_api.models.mental_model_trigger import MentalModelTrigger
+from hindsight_client_api.models.observation_evidence_response import ObservationEvidenceResponse
+from hindsight_client_api.models.observation_input import ObservationInput
 from hindsight_client_api.models.operation_response import OperationResponse
 from hindsight_client_api.models.operation_status_response import OperationStatusResponse
 from hindsight_client_api.models.operations_list_response import OperationsListResponse
@@ -86,7 +83,6 @@ from hindsight_client_api.models.recall_request import RecallRequest
 from hindsight_client_api.models.recall_response import RecallResponse
 from hindsight_client_api.models.recall_result import RecallResult
 from hindsight_client_api.models.reflect_based_on import ReflectBasedOn
-from hindsight_client_api.models.reflect_directive import ReflectDirective
 from hindsight_client_api.models.reflect_fact import ReflectFact
 from hindsight_client_api.models.reflect_include_options import ReflectIncludeOptions
 from hindsight_client_api.models.reflect_llm_call import ReflectLLMCall
@@ -95,14 +91,13 @@ from hindsight_client_api.models.reflect_request import ReflectRequest
 from hindsight_client_api.models.reflect_response import ReflectResponse
 from hindsight_client_api.models.reflect_tool_call import ReflectToolCall
 from hindsight_client_api.models.reflect_trace import ReflectTrace
+from hindsight_client_api.models.refresh_mental_models_request import RefreshMentalModelsRequest
 from hindsight_client_api.models.retain_request import RetainRequest
 from hindsight_client_api.models.retain_response import RetainResponse
 from hindsight_client_api.models.tag_item import TagItem
 from hindsight_client_api.models.token_usage import TokenUsage
 from hindsight_client_api.models.tool_calls_include_options import ToolCallsIncludeOptions
-from hindsight_client_api.models.update_directive_request import UpdateDirectiveRequest
 from hindsight_client_api.models.update_disposition_request import UpdateDispositionRequest
 from hindsight_client_api.models.update_mental_model_request import UpdateMentalModelRequest
 from hindsight_client_api.models.validation_error import ValidationError
 from hindsight_client_api.models.validation_error_loc_inner import ValidationErrorLocInner
-from hindsight_client_api.models.version_response import VersionResponse

hindsight-clients/python/hindsight_client_api/api/__init__.py

@@ -2,7 +2,6 @@
 
 # import apis into api package
 from hindsight_client_api.api.banks_api import BanksApi
-from hindsight_client_api.api.directives_api import DirectivesApi
 from hindsight_client_api.api.documents_api import DocumentsApi
 from hindsight_client_api.api.entities_api import EntitiesApi
 from hindsight_client_api.api.memory_api import MemoryApi

hindsight-clients/python/hindsight_client_api/api/banks_api.py

@@ -23,7 +23,6 @@ from hindsight_client_api.models.background_response import BackgroundResponse
 from hindsight_client_api.models.bank_list_response import BankListResponse
 from hindsight_client_api.models.bank_profile_response import BankProfileResponse
 from hindsight_client_api.models.bank_stats_response import BankStatsResponse
-from hindsight_client_api.models.consolidation_response import ConsolidationResponse
 from hindsight_client_api.models.create_bank_request import CreateBankRequest
 from hindsight_client_api.models.delete_response import DeleteResponse
 from hindsight_client_api.models.update_disposition_request import UpdateDispositionRequest
@@ -355,284 +354,6 @@ class BanksApi:
 
 
 
-    @validate_call
-    async def clear_observations(
-        self,
-        bank_id: StrictStr,
-        authorization: Optional[StrictStr] = None,
-        _request_timeout: Union[
-            None,
-            Annotated[StrictFloat, Field(gt=0)],
-            Tuple[
-                Annotated[StrictFloat, Field(gt=0)],
-                Annotated[StrictFloat, Field(gt=0)]
-            ]
-        ] = None,
-        _request_auth: Optional[Dict[StrictStr, Any]] = None,
-        _content_type: Optional[StrictStr] = None,
-        _headers: Optional[Dict[StrictStr, Any]] = None,
-        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
-    ) -> DeleteResponse:
-        """Clear all observations
-
-        Delete all observations for a memory bank. This is useful for resetting the consolidated knowledge.
-
-        :param bank_id: (required)
-        :type bank_id: str
-        :param authorization:
-        :type authorization: str
-        :param _request_timeout: timeout setting for this request. If one
-                                 number provided, it will be total request
-                                 timeout. It can also be a pair (tuple) of
-                                 (connection, read) timeouts.
-        :type _request_timeout: int, tuple(int, int), optional
-        :param _request_auth: set to override the auth_settings for an a single
-                              request; this effectively ignores the
-                              authentication in the spec for a single request.
-        :type _request_auth: dict, optional
-        :param _content_type: force content-type for the request.
-        :type _content_type: str, Optional
-        :param _headers: set to override the headers for a single
-                         request; this effectively ignores the headers
-                         in the spec for a single request.
-        :type _headers: dict, optional
-        :param _host_index: set to override the host_index for a single
-                            request; this effectively ignores the host_index
-                            in the spec for a single request.
-        :type _host_index: int, optional
-        :return: Returns the result object.
-        """ # noqa: E501
-
-        _param = self._clear_observations_serialize(
-            bank_id=bank_id,
-            authorization=authorization,
-            _request_auth=_request_auth,
-            _content_type=_content_type,
-            _headers=_headers,
-            _host_index=_host_index
-        )
-
-        _response_types_map: Dict[str, Optional[str]] = {
-            '200': "DeleteResponse",
-            '422': "HTTPValidationError",
-        }
-        response_data = await self.api_client.call_api(
-            *_param,
-            _request_timeout=_request_timeout
-        )
-        await response_data.read()
-        return self.api_client.response_deserialize(
-            response_data=response_data,
-            response_types_map=_response_types_map,
-        ).data
-
-
-    @validate_call
-    async def clear_observations_with_http_info(
-        self,
-        bank_id: StrictStr,
-        authorization: Optional[StrictStr] = None,
-        _request_timeout: Union[
-            None,
-            Annotated[StrictFloat, Field(gt=0)],
-            Tuple[
-                Annotated[StrictFloat, Field(gt=0)],
-                Annotated[StrictFloat, Field(gt=0)]
-            ]
-        ] = None,
-        _request_auth: Optional[Dict[StrictStr, Any]] = None,
-        _content_type: Optional[StrictStr] = None,
-        _headers: Optional[Dict[StrictStr, Any]] = None,
-        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
-    ) -> ApiResponse[DeleteResponse]:
-        """Clear all observations
-
-        Delete all observations for a memory bank. This is useful for resetting the consolidated knowledge.
-
-        :param bank_id: (required)
-        :type bank_id: str
-        :param authorization:
-        :type authorization: str
-        :param _request_timeout: timeout setting for this request. If one
-                                 number provided, it will be total request
-                                 timeout. It can also be a pair (tuple) of
-                                 (connection, read) timeouts.
-        :type _request_timeout: int, tuple(int, int), optional
-        :param _request_auth: set to override the auth_settings for an a single
-                              request; this effectively ignores the
-                              authentication in the spec for a single request.
-        :type _request_auth: dict, optional
-        :param _content_type: force content-type for the request.
-        :type _content_type: str, Optional
-        :param _headers: set to override the headers for a single
-                         request; this effectively ignores the headers
-                         in the spec for a single request.
-        :type _headers: dict, optional
-        :param _host_index: set to override the host_index for a single
-                            request; this effectively ignores the host_index
-                            in the spec for a single request.
-        :type _host_index: int, optional
-        :return: Returns the result object.
-        """ # noqa: E501
-
-        _param = self._clear_observations_serialize(
-            bank_id=bank_id,
-            authorization=authorization,
-            _request_auth=_request_auth,
-            _content_type=_content_type,
-            _headers=_headers,
-            _host_index=_host_index
-        )
-
-        _response_types_map: Dict[str, Optional[str]] = {
-            '200': "DeleteResponse",
-            '422': "HTTPValidationError",
-        }
-        response_data = await self.api_client.call_api(
-            *_param,
-            _request_timeout=_request_timeout
-        )
-        await response_data.read()
-        return self.api_client.response_deserialize(
-            response_data=response_data,
-            response_types_map=_response_types_map,
-        )
-
-
-    @validate_call
-    async def clear_observations_without_preload_content(
-        self,
-        bank_id: StrictStr,
-        authorization: Optional[StrictStr] = None,
-        _request_timeout: Union[
-            None,
-            Annotated[StrictFloat, Field(gt=0)],
-            Tuple[
-                Annotated[StrictFloat, Field(gt=0)],
-                Annotated[StrictFloat, Field(gt=0)]
-            ]
-        ] = None,
-        _request_auth: Optional[Dict[StrictStr, Any]] = None,
-        _content_type: Optional[StrictStr] = None,
-        _headers: Optional[Dict[StrictStr, Any]] = None,
-        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
-    ) -> RESTResponseType:
-        """Clear all observations
-
-        Delete all observations for a memory bank. This is useful for resetting the consolidated knowledge.
-
-        :param bank_id: (required)
-        :type bank_id: str
-        :param authorization:
-        :type authorization: str
-        :param _request_timeout: timeout setting for this request. If one
-                                 number provided, it will be total request
-                                 timeout. It can also be a pair (tuple) of
-                                 (connection, read) timeouts.
-        :type _request_timeout: int, tuple(int, int), optional
-        :param _request_auth: set to override the auth_settings for an a single
-                              request; this effectively ignores the
-                              authentication in the spec for a single request.
-        :type _request_auth: dict, optional
-        :param _content_type: force content-type for the request.
-        :type _content_type: str, Optional
-        :param _headers: set to override the headers for a single
-                         request; this effectively ignores the headers
-                         in the spec for a single request.
-        :type _headers: dict, optional
-        :param _host_index: set to override the host_index for a single
-                            request; this effectively ignores the host_index
-                            in the spec for a single request.
-        :type _host_index: int, optional
-        :return: Returns the result object.
-        """ # noqa: E501
-
-        _param = self._clear_observations_serialize(
-            bank_id=bank_id,
-            authorization=authorization,
-            _request_auth=_request_auth,
-            _content_type=_content_type,
-            _headers=_headers,
-            _host_index=_host_index
-        )
-
-        _response_types_map: Dict[str, Optional[str]] = {
-            '200': "DeleteResponse",
-            '422': "HTTPValidationError",
-        }
-        response_data = await self.api_client.call_api(
-            *_param,
-            _request_timeout=_request_timeout
-        )
-        return response_data.response
-
-
-    def _clear_observations_serialize(
-        self,
-        bank_id,
-        authorization,
-        _request_auth,
-        _content_type,
-        _headers,
-        _host_index,
-    ) -> RequestSerialized:
-
-        _host = None
-
-        _collection_formats: Dict[str, str] = {
-        }
-
-        _path_params: Dict[str, str] = {}
-        _query_params: List[Tuple[str, str]] = []
-        _header_params: Dict[str, Optional[str]] = _headers or {}
-        _form_params: List[Tuple[str, str]] = []
-        _files: Dict[
-            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
-        ] = {}
-        _body_params: Optional[bytes] = None
-
-        # process the path parameters
-        if bank_id is not None:
-            _path_params['bank_id'] = bank_id
-        # process the query parameters
-        # process the header parameters
-        if authorization is not None:
-            _header_params['authorization'] = authorization
-        # process the form parameters
-        # process the body parameter
-
-
-        # set the HTTP header `Accept`
-        if 'Accept' not in _header_params:
-            _header_params['Accept'] = self.api_client.select_header_accept(
-                [
-                    'application/json'
-                ]
-            )
-
-
-        # authentication setting
-        _auth_settings: List[str] = [
-        ]
-
-        return self.api_client.param_serialize(
-            method='DELETE',
-            resource_path='/v1/default/banks/{bank_id}/observations',
-            path_params=_path_params,
-            query_params=_query_params,
-            header_params=_header_params,
-            body=_body_params,
-            post_params=_form_params,
-            files=_files,
-            auth_settings=_auth_settings,
-            collection_formats=_collection_formats,
-            _host=_host,
-            _request_auth=_request_auth
-        )
-
-
-
-
     @validate_call
     async def create_or_update_bank(
         self,
@@ -2036,284 +1757,6 @@ class BanksApi:
 
 
 
-    @validate_call
-    async def trigger_consolidation(
-        self,
-        bank_id: StrictStr,
-        authorization: Optional[StrictStr] = None,
-        _request_timeout: Union[
-            None,
-            Annotated[StrictFloat, Field(gt=0)],
-            Tuple[
-                Annotated[StrictFloat, Field(gt=0)],
-                Annotated[StrictFloat, Field(gt=0)]
-            ]
-        ] = None,
-        _request_auth: Optional[Dict[StrictStr, Any]] = None,
-        _content_type: Optional[StrictStr] = None,
-        _headers: Optional[Dict[StrictStr, Any]] = None,
-        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
-    ) -> ConsolidationResponse:
-        """Trigger consolidation
-
-        Run memory consolidation to create/update observations from recent memories.
-
-        :param bank_id: (required)
-        :type bank_id: str
-        :param authorization:
-        :type authorization: str
-        :param _request_timeout: timeout setting for this request. If one
-                                 number provided, it will be total request
-                                 timeout. It can also be a pair (tuple) of
-                                 (connection, read) timeouts.
-        :type _request_timeout: int, tuple(int, int), optional
-        :param _request_auth: set to override the auth_settings for an a single
-                              request; this effectively ignores the
-                              authentication in the spec for a single request.
-        :type _request_auth: dict, optional
-        :param _content_type: force content-type for the request.
-        :type _content_type: str, Optional
-        :param _headers: set to override the headers for a single
-                         request; this effectively ignores the headers
-                         in the spec for a single request.
-        :type _headers: dict, optional
-        :param _host_index: set to override the host_index for a single
-                            request; this effectively ignores the host_index
-                            in the spec for a single request.
-        :type _host_index: int, optional
-        :return: Returns the result object.
-        """ # noqa: E501
-
-        _param = self._trigger_consolidation_serialize(
-            bank_id=bank_id,
-            authorization=authorization,
-            _request_auth=_request_auth,
-            _content_type=_content_type,
-            _headers=_headers,
-            _host_index=_host_index
-        )
-
-        _response_types_map: Dict[str, Optional[str]] = {
-            '200': "ConsolidationResponse",
-            '422': "HTTPValidationError",
-        }
-        response_data = await self.api_client.call_api(
-            *_param,
-            _request_timeout=_request_timeout
-        )
-        await response_data.read()
-        return self.api_client.response_deserialize(
-            response_data=response_data,
-            response_types_map=_response_types_map,
-        ).data
-
-
-    @validate_call
-    async def trigger_consolidation_with_http_info(
-        self,
-        bank_id: StrictStr,
-        authorization: Optional[StrictStr] = None,
-        _request_timeout: Union[
-            None,
-            Annotated[StrictFloat, Field(gt=0)],
-            Tuple[
-                Annotated[StrictFloat, Field(gt=0)],
-                Annotated[StrictFloat, Field(gt=0)]
-            ]
-        ] = None,
-        _request_auth: Optional[Dict[StrictStr, Any]] = None,
-        _content_type: Optional[StrictStr] = None,
-        _headers: Optional[Dict[StrictStr, Any]] = None,
-        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
-    ) -> ApiResponse[ConsolidationResponse]:
-        """Trigger consolidation
-
-        Run memory consolidation to create/update observations from recent memories.
-
-        :param bank_id: (required)
-        :type bank_id: str
-        :param authorization:
-        :type authorization: str
-        :param _request_timeout: timeout setting for this request. If one
-                                 number provided, it will be total request
-                                 timeout. It can also be a pair (tuple) of
-                                 (connection, read) timeouts.
-        :type _request_timeout: int, tuple(int, int), optional
-        :param _request_auth: set to override the auth_settings for an a single
-                              request; this effectively ignores the
-                              authentication in the spec for a single request.
-        :type _request_auth: dict, optional
-        :param _content_type: force content-type for the request.
-        :type _content_type: str, Optional
-        :param _headers: set to override the headers for a single
-                         request; this effectively ignores the headers
-                         in the spec for a single request.
-        :type _headers: dict, optional
-        :param _host_index: set to override the host_index for a single
-                            request; this effectively ignores the host_index
-                            in the spec for a single request.
-        :type _host_index: int, optional
-        :return: Returns the result object.
-        """ # noqa: E501
-
-        _param = self._trigger_consolidation_serialize(
-            bank_id=bank_id,
-            authorization=authorization,
-            _request_auth=_request_auth,
-            _content_type=_content_type,
-            _headers=_headers,
-            _host_index=_host_index
-        )
-
-        _response_types_map: Dict[str, Optional[str]] = {
-            '200': "ConsolidationResponse",
-            '422': "HTTPValidationError",
-        }
-        response_data = await self.api_client.call_api(
-            *_param,
-            _request_timeout=_request_timeout
-        )
-        await response_data.read()
-        return self.api_client.response_deserialize(
-            response_data=response_data,
-            response_types_map=_response_types_map,
-        )
-
-
-    @validate_call
-    async def trigger_consolidation_without_preload_content(
-        self,
-        bank_id: StrictStr,
-        authorization: Optional[StrictStr] = None,
-        _request_timeout: Union[
-            None,
-            Annotated[StrictFloat, Field(gt=0)],
-            Tuple[
-                Annotated[StrictFloat, Field(gt=0)],
-                Annotated[StrictFloat, Field(gt=0)]
-            ]
-        ] = None,
-        _request_auth: Optional[Dict[StrictStr, Any]] = None,
-        _content_type: Optional[StrictStr] = None,
-        _headers: Optional[Dict[StrictStr, Any]] = None,
-        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
-    ) -> RESTResponseType:
-        """Trigger consolidation
-
-        Run memory consolidation to create/update observations from recent memories.
-
-        :param bank_id: (required)
-        :type bank_id: str
-        :param authorization:
-        :type authorization: str
-        :param _request_timeout: timeout setting for this request. If one
-                                 number provided, it will be total request
-                                 timeout. It can also be a pair (tuple) of
-                                 (connection, read) timeouts.
-        :type _request_timeout: int, tuple(int, int), optional
-        :param _request_auth: set to override the auth_settings for an a single
-                              request; this effectively ignores the
-                              authentication in the spec for a single request.
-        :type _request_auth: dict, optional
-        :param _content_type: force content-type for the request.
-        :type _content_type: str, Optional
-        :param _headers: set to override the headers for a single
-                         request; this effectively ignores the headers
-                         in the spec for a single request.
-        :type _headers: dict, optional
-        :param _host_index: set to override the host_index for a single
-                            request; this effectively ignores the host_index
-                            in the spec for a single request.
-        :type _host_index: int, optional
-        :return: Returns the result object.
-        """ # noqa: E501
-
-        _param = self._trigger_consolidation_serialize(
-            bank_id=bank_id,
-            authorization=authorization,
-            _request_auth=_request_auth,
-            _content_type=_content_type,
-            _headers=_headers,
-            _host_index=_host_index
-        )
-
-        _response_types_map: Dict[str, Optional[str]] = {
-            '200': "ConsolidationResponse",
-            '422': "HTTPValidationError",
-        }
-        response_data = await self.api_client.call_api(
-            *_param,
-            _request_timeout=_request_timeout
-        )
-        return response_data.response
-
-
-    def _trigger_consolidation_serialize(
-        self,
-        bank_id,
-        authorization,
-        _request_auth,
-        _content_type,
-        _headers,
-        _host_index,
-    ) -> RequestSerialized:
-
-        _host = None
-
-        _collection_formats: Dict[str, str] = {
-        }
-
-        _path_params: Dict[str, str] = {}
-        _query_params: List[Tuple[str, str]] = []
-        _header_params: Dict[str, Optional[str]] = _headers or {}
-        _form_params: List[Tuple[str, str]] = []
-        _files: Dict[
-            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
-        ] = {}
-        _body_params: Optional[bytes] = None
-
-        # process the path parameters
-        if bank_id is not None:
-            _path_params['bank_id'] = bank_id
-        # process the query parameters
-        # process the header parameters
-        if authorization is not None:
-            _header_params['authorization'] = authorization
-        # process the form parameters
-        # process the body parameter
-
-
-        # set the HTTP header `Accept`
-        if 'Accept' not in _header_params:
-            _header_params['Accept'] = self.api_client.select_header_accept(
-                [
-                    'application/json'
-                ]
-            )
-
-
-        # authentication setting
-        _auth_settings: List[str] = [
-        ]
-
-        return self.api_client.param_serialize(
-            method='POST',
-            resource_path='/v1/default/banks/{bank_id}/consolidate',
-            path_params=_path_params,
-            query_params=_query_params,
-            header_params=_header_params,
-            body=_body_params,
-            post_params=_form_params,
-            files=_files,
-            auth_settings=_auth_settings,
-            collection_formats=_collection_formats,
-            _host=_host,
-            _request_auth=_request_auth
-        )
-
-
-
-
     @validate_call
     async def update_bank(
         self,

hindsight-clients/python/hindsight_client_api/api/monitoring_api.py

@@ -17,7 +17,6 @@ from typing import Any, Dict, List, Optional, Tuple, Union
 from typing_extensions import Annotated
 
 from typing import Any
-from hindsight_client_api.models.version_response import VersionResponse
 
 from hindsight_client_api.api_client import ApiClient, RequestSerialized
 from hindsight_client_api.api_response import ApiResponse
@@ -37,251 +36,6 @@ class MonitoringApi:
         self.api_client = api_client
 
 
-    @validate_call
-    async def get_version(
-        self,
-        _request_timeout: Union[
-            None,
-            Annotated[StrictFloat, Field(gt=0)],
-            Tuple[
-                Annotated[StrictFloat, Field(gt=0)],
-                Annotated[StrictFloat, Field(gt=0)]
-            ]
-        ] = None,
-        _request_auth: Optional[Dict[StrictStr, Any]] = None,
-        _content_type: Optional[StrictStr] = None,
-        _headers: Optional[Dict[StrictStr, Any]] = None,
-        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
-    ) -> VersionResponse:
-        """Get API version and feature flags
-
-        Returns API version information and enabled feature flags. Use this to check which capabilities are available in this deployment.
-
-        :param _request_timeout: timeout setting for this request. If one
-                                 number provided, it will be total request
-                                 timeout. It can also be a pair (tuple) of
-                                 (connection, read) timeouts.
-        :type _request_timeout: int, tuple(int, int), optional
-        :param _request_auth: set to override the auth_settings for an a single
-                              request; this effectively ignores the
-                              authentication in the spec for a single request.
-        :type _request_auth: dict, optional
-        :param _content_type: force content-type for the request.
-        :type _content_type: str, Optional
-        :param _headers: set to override the headers for a single
-                         request; this effectively ignores the headers
-                         in the spec for a single request.
-        :type _headers: dict, optional
-        :param _host_index: set to override the host_index for a single
-                            request; this effectively ignores the host_index
-                            in the spec for a single request.
-        :type _host_index: int, optional
-        :return: Returns the result object.
-        """ # noqa: E501
-
-        _param = self._get_version_serialize(
-            _request_auth=_request_auth,
-            _content_type=_content_type,
-            _headers=_headers,
-            _host_index=_host_index
-        )
-
-        _response_types_map: Dict[str, Optional[str]] = {
-            '200': "VersionResponse",
-        }
-        response_data = await self.api_client.call_api(
-            *_param,
-            _request_timeout=_request_timeout
-        )
-        await response_data.read()
-        return self.api_client.response_deserialize(
-            response_data=response_data,
-            response_types_map=_response_types_map,
-        ).data
-
-
-    @validate_call
-    async def get_version_with_http_info(
-        self,
-        _request_timeout: Union[
-            None,
-            Annotated[StrictFloat, Field(gt=0)],
-            Tuple[
-                Annotated[StrictFloat, Field(gt=0)],
-                Annotated[StrictFloat, Field(gt=0)]
-            ]
-        ] = None,
-        _request_auth: Optional[Dict[StrictStr, Any]] = None,
-        _content_type: Optional[StrictStr] = None,
-        _headers: Optional[Dict[StrictStr, Any]] = None,
-        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
-    ) -> ApiResponse[VersionResponse]:
-        """Get API version and feature flags
-
-        Returns API version information and enabled feature flags. Use this to check which capabilities are available in this deployment.
-
-        :param _request_timeout: timeout setting for this request. If one
-                                 number provided, it will be total request
-                                 timeout. It can also be a pair (tuple) of
-                                 (connection, read) timeouts.
-        :type _request_timeout: int, tuple(int, int), optional
-        :param _request_auth: set to override the auth_settings for an a single
-                              request; this effectively ignores the
-                              authentication in the spec for a single request.
-        :type _request_auth: dict, optional
-        :param _content_type: force content-type for the request.
-        :type _content_type: str, Optional
-        :param _headers: set to override the headers for a single
-                         request; this effectively ignores the headers
-                         in the spec for a single request.
-        :type _headers: dict, optional
-        :param _host_index: set to override the host_index for a single
-                            request; this effectively ignores the host_index
-                            in the spec for a single request.
-        :type _host_index: int, optional
-        :return: Returns the result object.
-        """ # noqa: E501
-
-        _param = self._get_version_serialize(
-            _request_auth=_request_auth,
-            _content_type=_content_type,
-            _headers=_headers,
-            _host_index=_host_index
-        )
-
-        _response_types_map: Dict[str, Optional[str]] = {
-            '200': "VersionResponse",
-        }
-        response_data = await self.api_client.call_api(
-            *_param,
-            _request_timeout=_request_timeout
-        )
-        await response_data.read()
-        return self.api_client.response_deserialize(
-            response_data=response_data,
-            response_types_map=_response_types_map,
-        )
-
-
-    @validate_call
-    async def get_version_without_preload_content(
-        self,
-        _request_timeout: Union[
-            None,
-            Annotated[StrictFloat, Field(gt=0)],
-            Tuple[
-                Annotated[StrictFloat, Field(gt=0)],
-                Annotated[StrictFloat, Field(gt=0)]
-            ]
-        ] = None,
-        _request_auth: Optional[Dict[StrictStr, Any]] = None,
-        _content_type: Optional[StrictStr] = None,
-        _headers: Optional[Dict[StrictStr, Any]] = None,
-        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
-    ) -> RESTResponseType:
-        """Get API version and feature flags
-
-        Returns API version information and enabled feature flags. Use this to check which capabilities are available in this deployment.
-
-        :param _request_timeout: timeout setting for this request. If one
-                                 number provided, it will be total request
-                                 timeout. It can also be a pair (tuple) of
-                                 (connection, read) timeouts.
-        :type _request_timeout: int, tuple(int, int), optional
-        :param _request_auth: set to override the auth_settings for an a single
-                              request; this effectively ignores the
-                              authentication in the spec for a single request.
-        :type _request_auth: dict, optional
-        :param _content_type: force content-type for the request.
-        :type _content_type: str, Optional
-        :param _headers: set to override the headers for a single
-                         request; this effectively ignores the headers
-                         in the spec for a single request.
-        :type _headers: dict, optional
-        :param _host_index: set to override the host_index for a single
-                            request; this effectively ignores the host_index
-                            in the spec for a single request.
-        :type _host_index: int, optional
-        :return: Returns the result object.
-        """ # noqa: E501
-
-        _param = self._get_version_serialize(
-            _request_auth=_request_auth,
-            _content_type=_content_type,
-            _headers=_headers,
-            _host_index=_host_index
-        )
-
-        _response_types_map: Dict[str, Optional[str]] = {
-            '200': "VersionResponse",
-        }
-        response_data = await self.api_client.call_api(
-            *_param,
-            _request_timeout=_request_timeout
-        )
-        return response_data.response
-
-
-    def _get_version_serialize(
-        self,
-        _request_auth,
-        _content_type,
-        _headers,
-        _host_index,
-    ) -> RequestSerialized:
-
-        _host = None
-
-        _collection_formats: Dict[str, str] = {
-        }
-
-        _path_params: Dict[str, str] = {}
-        _query_params: List[Tuple[str, str]] = []
-        _header_params: Dict[str, Optional[str]] = _headers or {}
-        _form_params: List[Tuple[str, str]] = []
-        _files: Dict[
-            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
-        ] = {}
-        _body_params: Optional[bytes] = None
-
-        # process the path parameters
-        # process the query parameters
-        # process the header parameters
-        # process the form parameters
-        # process the body parameter
-
-
-        # set the HTTP header `Accept`
-        if 'Accept' not in _header_params:
-            _header_params['Accept'] = self.api_client.select_header_accept(
-                [
-                    'application/json'
-                ]
-            )
-
-
-        # authentication setting
-        _auth_settings: List[str] = [
-        ]
-
-        return self.api_client.param_serialize(
-            method='GET',
-            resource_path='/version',
-            path_params=_path_params,
-            query_params=_query_params,
-            header_params=_header_params,
-            body=_body_params,
-            post_params=_form_params,
-            files=_files,
-            auth_settings=_auth_settings,
-            collection_formats=_collection_formats,
-            _host=_host,
-            _request_auth=_request_auth
-        )
-
-
-
-
     @validate_call
     async def health_endpoint_health_get(
         self,

hindsight-clients/python/hindsight_client_api/api/operations_api.py

@@ -16,9 +16,8 @@ from pydantic import validate_call, Field, StrictFloat, StrictStr, StrictInt
 from typing import Any, Dict, List, Optional, Tuple, Union
 from typing_extensions import Annotated
 
-from pydantic import Field, StrictStr
+from pydantic import StrictStr
 from typing import Optional
-from typing_extensions import Annotated
 from hindsight_client_api.models.cancel_operation_response import CancelOperationResponse
 from hindsight_client_api.models.operation_status_response import OperationStatusResponse
 from hindsight_client_api.models.operations_list_response import OperationsListResponse
@@ -631,9 +630,6 @@ class OperationsApi:
     async def list_operations(
         self,
         bank_id: StrictStr,
-        status: Annotated[Optional[StrictStr], Field(description="Filter by status: pending, completed, or failed")] = None,
-        limit: Annotated[Optional[Annotated[int, Field(le=100, strict=True, ge=1)]], Field(description="Maximum number of operations to return")] = None,
-        offset: Annotated[Optional[Annotated[int, Field(strict=True, ge=0)]], Field(description="Number of operations to skip")] = None,
         authorization: Optional[StrictStr] = None,
         _request_timeout: Union[
             None,
@@ -650,16 +646,10 @@ class OperationsApi:
     ) -> OperationsListResponse:
         """List async operations
 
-        Get a list of async operations for a specific agent, with optional filtering by status. Results are sorted by most recent first.
+        Get a list of all async operations (pending and failed) for a specific agent, including error messages for failed operations
 
         :param bank_id: (required)
         :type bank_id: str
-        :param status: Filter by status: pending, completed, or failed
-        :type status: str
-        :param limit: Maximum number of operations to return
-        :type limit: int
-        :param offset: Number of operations to skip
-        :type offset: int
         :param authorization:
         :type authorization: str
         :param _request_timeout: timeout setting for this request. If one
@@ -686,9 +676,6 @@ class OperationsApi:
 
         _param = self._list_operations_serialize(
             bank_id=bank_id,
-            status=status,
-            limit=limit,
-            offset=offset,
             authorization=authorization,
             _request_auth=_request_auth,
             _content_type=_content_type,
@@ -715,9 +702,6 @@ class OperationsApi:
     async def list_operations_with_http_info(
         self,
         bank_id: StrictStr,
-        status: Annotated[Optional[StrictStr], Field(description="Filter by status: pending, completed, or failed")] = None,
-        limit: Annotated[Optional[Annotated[int, Field(le=100, strict=True, ge=1)]], Field(description="Maximum number of operations to return")] = None,
-        offset: Annotated[Optional[Annotated[int, Field(strict=True, ge=0)]], Field(description="Number of operations to skip")] = None,
         authorization: Optional[StrictStr] = None,
         _request_timeout: Union[
             None,
@@ -734,16 +718,10 @@ class OperationsApi:
     ) -> ApiResponse[OperationsListResponse]:
         """List async operations
 
-        Get a list of async operations for a specific agent, with optional filtering by status. Results are sorted by most recent first.
+        Get a list of all async operations (pending and failed) for a specific agent, including error messages for failed operations
 
         :param bank_id: (required)
         :type bank_id: str
-        :param status: Filter by status: pending, completed, or failed
-        :type status: str
-        :param limit: Maximum number of operations to return
-        :type limit: int
-        :param offset: Number of operations to skip
-        :type offset: int
         :param authorization:
         :type authorization: str
         :param _request_timeout: timeout setting for this request. If one
@@ -770,9 +748,6 @@ class OperationsApi:
 
         _param = self._list_operations_serialize(
             bank_id=bank_id,
-            status=status,
-            limit=limit,
-            offset=offset,
             authorization=authorization,
             _request_auth=_request_auth,
             _content_type=_content_type,
@@ -799,9 +774,6 @@ class OperationsApi:
     async def list_operations_without_preload_content(
         self,
         bank_id: StrictStr,
-        status: Annotated[Optional[StrictStr], Field(description="Filter by status: pending, completed, or failed")] = None,
-        limit: Annotated[Optional[Annotated[int, Field(le=100, strict=True, ge=1)]], Field(description="Maximum number of operations to return")] = None,
-        offset: Annotated[Optional[Annotated[int, Field(strict=True, ge=0)]], Field(description="Number of operations to skip")] = None,
         authorization: Optional[StrictStr] = None,
         _request_timeout: Union[
             None,
@@ -818,16 +790,10 @@ class OperationsApi:
     ) -> RESTResponseType:
         """List async operations
 
-        Get a list of async operations for a specific agent, with optional filtering by status. Results are sorted by most recent first.
+        Get a list of all async operations (pending and failed) for a specific agent, including error messages for failed operations
 
         :param bank_id: (required)
         :type bank_id: str
-        :param status: Filter by status: pending, completed, or failed
-        :type status: str
-        :param limit: Maximum number of operations to return
-        :type limit: int
-        :param offset: Number of operations to skip
-        :type offset: int
         :param authorization:
         :type authorization: str
         :param _request_timeout: timeout setting for this request. If one
@@ -854,9 +820,6 @@ class OperationsApi:
 
         _param = self._list_operations_serialize(
             bank_id=bank_id,
-            status=status,
-            limit=limit,
-            offset=offset,
             authorization=authorization,
             _request_auth=_request_auth,
             _content_type=_content_type,
@@ -878,9 +841,6 @@ class OperationsApi:
     def _list_operations_serialize(
         self,
         bank_id,
-        status,
-        limit,
-        offset,
         authorization,
         _request_auth,
         _content_type,
@@ -906,18 +866,6 @@ class OperationsApi:
         if bank_id is not None:
             _path_params['bank_id'] = bank_id
         # process the query parameters
-        if status is not None:
-            
-            _query_params.append(('status', status))
-            
-        if limit is not None:
-            
-            _query_params.append(('limit', limit))
-            
-        if offset is not None:
-            
-            _query_params.append(('offset', offset))
-            
         # process the header parameters
         if authorization is not None:
             _header_params['authorization'] = authorization

hindsight-clients/python/hindsight_client_api/models/__init__.py

@@ -26,15 +26,11 @@ from hindsight_client_api.models.cancel_operation_response import CancelOperatio
 from hindsight_client_api.models.chunk_data import ChunkData
 from hindsight_client_api.models.chunk_include_options import ChunkIncludeOptions
 from hindsight_client_api.models.chunk_response import ChunkResponse
-from hindsight_client_api.models.consolidation_response import ConsolidationResponse
 from hindsight_client_api.models.create_bank_request import CreateBankRequest
-from hindsight_client_api.models.create_directive_request import CreateDirectiveRequest
 from hindsight_client_api.models.create_mental_model_request import CreateMentalModelRequest
-from hindsight_client_api.models.create_mental_model_response import CreateMentalModelResponse
+from hindsight_client_api.models.created_mental_model import CreatedMentalModel
 from hindsight_client_api.models.delete_document_response import DeleteDocumentResponse
 from hindsight_client_api.models.delete_response import DeleteResponse
-from hindsight_client_api.models.directive_list_response import DirectiveListResponse
-from hindsight_client_api.models.directive_response import DirectiveResponse
 from hindsight_client_api.models.disposition_traits import DispositionTraits
 from hindsight_client_api.models.document_response import DocumentResponse
 from hindsight_client_api.models.entity_detail_response import EntityDetailResponse
@@ -44,7 +40,6 @@ from hindsight_client_api.models.entity_list_item import EntityListItem
 from hindsight_client_api.models.entity_list_response import EntityListResponse
 from hindsight_client_api.models.entity_observation_response import EntityObservationResponse
 from hindsight_client_api.models.entity_state_response import EntityStateResponse
-from hindsight_client_api.models.features_info import FeaturesInfo
 from hindsight_client_api.models.graph_data_response import GraphDataResponse
 from hindsight_client_api.models.http_validation_error import HTTPValidationError
 from hindsight_client_api.models.include_options import IncludeOptions
@@ -52,9 +47,12 @@ from hindsight_client_api.models.list_documents_response import ListDocumentsRes
 from hindsight_client_api.models.list_memory_units_response import ListMemoryUnitsResponse
 from hindsight_client_api.models.list_tags_response import ListTagsResponse
 from hindsight_client_api.models.memory_item import MemoryItem
+from hindsight_client_api.models.mental_model_freshness_response import MentalModelFreshnessResponse
 from hindsight_client_api.models.mental_model_list_response import MentalModelListResponse
+from hindsight_client_api.models.mental_model_observation_response import MentalModelObservationResponse
 from hindsight_client_api.models.mental_model_response import MentalModelResponse
-from hindsight_client_api.models.mental_model_trigger import MentalModelTrigger
+from hindsight_client_api.models.observation_evidence_response import ObservationEvidenceResponse
+from hindsight_client_api.models.observation_input import ObservationInput
 from hindsight_client_api.models.operation_response import OperationResponse
 from hindsight_client_api.models.operation_status_response import OperationStatusResponse
 from hindsight_client_api.models.operations_list_response import OperationsListResponse
@@ -62,7 +60,6 @@ from hindsight_client_api.models.recall_request import RecallRequest
 from hindsight_client_api.models.recall_response import RecallResponse
 from hindsight_client_api.models.recall_result import RecallResult
 from hindsight_client_api.models.reflect_based_on import ReflectBasedOn
-from hindsight_client_api.models.reflect_directive import ReflectDirective
 from hindsight_client_api.models.reflect_fact import ReflectFact
 from hindsight_client_api.models.reflect_include_options import ReflectIncludeOptions
 from hindsight_client_api.models.reflect_llm_call import ReflectLLMCall
@@ -71,14 +68,13 @@ from hindsight_client_api.models.reflect_request import ReflectRequest
 from hindsight_client_api.models.reflect_response import ReflectResponse
 from hindsight_client_api.models.reflect_tool_call import ReflectToolCall
 from hindsight_client_api.models.reflect_trace import ReflectTrace
+from hindsight_client_api.models.refresh_mental_models_request import RefreshMentalModelsRequest
 from hindsight_client_api.models.retain_request import RetainRequest
 from hindsight_client_api.models.retain_response import RetainResponse
 from hindsight_client_api.models.tag_item import TagItem
 from hindsight_client_api.models.token_usage import TokenUsage
 from hindsight_client_api.models.tool_calls_include_options import ToolCallsIncludeOptions
-from hindsight_client_api.models.update_directive_request import UpdateDirectiveRequest
 from hindsight_client_api.models.update_disposition_request import UpdateDispositionRequest
 from hindsight_client_api.models.update_mental_model_request import UpdateMentalModelRequest
 from hindsight_client_api.models.validation_error import ValidationError
 from hindsight_client_api.models.validation_error_loc_inner import ValidationErrorLocInner
-from hindsight_client_api.models.version_response import VersionResponse

hindsight-clients/python/hindsight_client_api/models/bank_stats_response.py

@@ -17,8 +17,8 @@ import pprint
 import re  # noqa: F401
 import json
 
-from pydantic import BaseModel, ConfigDict, Field, StrictInt, StrictStr
-from typing import Any, ClassVar, Dict, List, Optional
+from pydantic import BaseModel, ConfigDict, StrictInt, StrictStr
+from typing import Any, ClassVar, Dict, List
 from typing import Optional, Set
 from typing_extensions import Self
 
@@ -36,10 +36,7 @@ class BankStatsResponse(BaseModel):
     links_breakdown: Dict[str, Dict[str, StrictInt]]
     pending_operations: StrictInt
     failed_operations: StrictInt
-    last_consolidated_at: Optional[StrictStr] = None
-    pending_consolidation: Optional[StrictInt] = Field(default=0, description="Number of memories not yet processed into observations")
-    total_observations: Optional[StrictInt] = Field(default=0, description="Total number of observations")
-    __properties: ClassVar[List[str]] = ["bank_id", "total_nodes", "total_links", "total_documents", "nodes_by_fact_type", "links_by_link_type", "links_by_fact_type", "links_breakdown", "pending_operations", "failed_operations", "last_consolidated_at", "pending_consolidation", "total_observations"]
+    __properties: ClassVar[List[str]] = ["bank_id", "total_nodes", "total_links", "total_documents", "nodes_by_fact_type", "links_by_link_type", "links_by_fact_type", "links_breakdown", "pending_operations", "failed_operations"]
 
     model_config = ConfigDict(
         populate_by_name=True,
@@ -80,11 +77,6 @@ class BankStatsResponse(BaseModel):
             exclude=excluded_fields,
             exclude_none=True,
         )
-        # set to None if last_consolidated_at (nullable) is None
-        # and model_fields_set contains the field
-        if self.last_consolidated_at is None and "last_consolidated_at" in self.model_fields_set:
-            _dict['last_consolidated_at'] = None
-
         return _dict
 
     @classmethod
@@ -106,10 +98,7 @@ class BankStatsResponse(BaseModel):
             "links_by_fact_type": obj.get("links_by_fact_type"),
             "links_breakdown": obj.get("links_breakdown"),
             "pending_operations": obj.get("pending_operations"),
-            "failed_operations": obj.get("failed_operations"),
-            "last_consolidated_at": obj.get("last_consolidated_at"),
-            "pending_consolidation": obj.get("pending_consolidation") if obj.get("pending_consolidation") is not None else 0,
-            "total_observations": obj.get("total_observations") if obj.get("total_observations") is not None else 0
+            "failed_operations": obj.get("failed_operations")
         })
         return _obj
 

hindsight-clients/python/hindsight_client_api/models/create_mental_model_request.py

@@ -19,8 +19,7 @@ import json
 
 from pydantic import BaseModel, ConfigDict, Field, StrictStr
 from typing import Any, ClassVar, Dict, List, Optional
-from typing_extensions import Annotated
-from hindsight_client_api.models.mental_model_trigger import MentalModelTrigger
+from hindsight_client_api.models.observation_input import ObservationInput
 from typing import Optional, Set
 from typing_extensions import Self
 
@@ -29,11 +28,11 @@ class CreateMentalModelRequest(BaseModel):
     Request model for creating a mental model.
     """ # noqa: E501
     name: StrictStr = Field(description="Human-readable name for the mental model")
-    source_query: StrictStr = Field(description="The query to run to generate content")
+    description: StrictStr = Field(description="One-liner description for quick scanning")
+    subtype: Optional[StrictStr] = Field(default='pinned', description="Type of mental model: 'pinned' (observations LLM-generated) or 'directive' (observations user-provided)")
+    observations: Optional[List[ObservationInput]] = None
     tags: Optional[List[StrictStr]] = Field(default=None, description="Tags for scoped visibility")
-    max_tokens: Optional[Annotated[int, Field(le=8192, strict=True, ge=256)]] = Field(default=2048, description="Maximum tokens for generated content")
-    trigger: Optional[MentalModelTrigger] = Field(default=None, description="Trigger settings")
-    __properties: ClassVar[List[str]] = ["name", "source_query", "tags", "max_tokens", "trigger"]
+    __properties: ClassVar[List[str]] = ["name", "description", "subtype", "observations", "tags"]
 
     model_config = ConfigDict(
         populate_by_name=True,
@@ -74,9 +73,18 @@ class CreateMentalModelRequest(BaseModel):
             exclude=excluded_fields,
             exclude_none=True,
         )
-        # override the default output from pydantic by calling `to_dict()` of trigger
-        if self.trigger:
-            _dict['trigger'] = self.trigger.to_dict()
+        # override the default output from pydantic by calling `to_dict()` of each item in observations (list)
+        _items = []
+        if self.observations:
+            for _item_observations in self.observations:
+                if _item_observations:
+                    _items.append(_item_observations.to_dict())
+            _dict['observations'] = _items
+        # set to None if observations (nullable) is None
+        # and model_fields_set contains the field
+        if self.observations is None and "observations" in self.model_fields_set:
+            _dict['observations'] = None
+
         return _dict
 
     @classmethod
@@ -90,10 +98,10 @@ class CreateMentalModelRequest(BaseModel):
 
         _obj = cls.model_validate({
             "name": obj.get("name"),
-            "source_query": obj.get("source_query"),
-            "tags": obj.get("tags"),
-            "max_tokens": obj.get("max_tokens") if obj.get("max_tokens") is not None else 2048,
-            "trigger": MentalModelTrigger.from_dict(obj["trigger"]) if obj.get("trigger") is not None else None
+            "description": obj.get("description"),
+            "subtype": obj.get("subtype") if obj.get("subtype") is not None else 'pinned',
+            "observations": [ObservationInput.from_dict(_item) for _item in obj["observations"]] if obj.get("observations") is not None else None,
+            "tags": obj.get("tags")
         })
         return _obj