ci: add upgrade tests

.env.example

@@ -2,7 +2,7 @@
 # Copy this file to .env and fill in your values
 
 # LLM Configuration (Required)
-# Supported providers: openai, groq, ollama, gemini, anthropic, lmstudio, vertexai
+# Supported providers: openai, groq, ollama, gemini, anthropic, lmstudio
 HINDSIGHT_API_LLM_PROVIDER=openai
 HINDSIGHT_API_LLM_API_KEY=your-api-key-here
 HINDSIGHT_API_LLM_MODEL=o3-mini
@@ -13,13 +13,6 @@ HINDSIGHT_API_LLM_BASE_URL=https://api.openai.com/v1
 # HINDSIGHT_API_LLM_API_KEY=your-anthropic-api-key
 # HINDSIGHT_API_LLM_MODEL=claude-sonnet-4-20250514
 
-# Example: Google Vertex AI configuration
-# HINDSIGHT_API_LLM_PROVIDER=vertexai
-# HINDSIGHT_API_LLM_MODEL=google/gemini-2.0-flash-001
-# HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=your-gcp-project-id
-# HINDSIGHT_API_LLM_VERTEXAI_REGION=us-central1
-# HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY=/path/to/service-account-key.json  # Optional, uses ADC if not set
-
 # Example: LM Studio local configuration (Qwen 2.5 32B recommended)
 # HINDSIGHT_API_LLM_PROVIDER=lmstudio
 # HINDSIGHT_API_LLM_API_KEY=lmstudio
@@ -33,7 +26,6 @@ HINDSIGHT_API_LOG_LEVEL=info
 
 # Database (Optional - uses embedded pg0 by default)
 # HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@host:5432/db
-# HINDSIGHT_API_DATABASE_SCHEMA=public  # PostgreSQL schema name (default: public)
 
 # Embeddings Configuration (Optional - uses local by default)
 # Provider: "local" (default) or "tei" (HuggingFace Text Embeddings Inference)

.github/workflows/release.yml

@@ -139,55 +139,6 @@ jobs:
         path: hindsight-clients/typescript/*.tgz
         retention-days: 1
 
-  release-moltbot-integration:
-    runs-on: ubuntu-latest
-    environment: npm
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: '22'
-        registry-url: 'https://registry.npmjs.org'
-
-    - name: Install dependencies
-      working-directory: ./hindsight-integrations/moltbot
-      run: npm ci
-
-    - name: Build
-      working-directory: ./hindsight-integrations/moltbot
-      run: npm run build
-
-    - name: Publish to npm
-      working-directory: ./hindsight-integrations/moltbot
-      run: |
-        set +e
-        OUTPUT=$(npm publish --access public 2>&1)
-        EXIT_CODE=$?
-        echo "$OUTPUT"
-        if [ $EXIT_CODE -ne 0 ]; then
-          if echo "$OUTPUT" | grep -q "cannot publish over"; then
-            echo "Package version already published, skipping..."
-            exit 0
-          fi
-          exit $EXIT_CODE
-        fi
-      env:
-        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-    - name: Pack for GitHub release
-      working-directory: ./hindsight-integrations/moltbot
-      run: npm pack
-
-    - name: Upload artifacts
-      uses: actions/upload-artifact@v4
-      with:
-        name: moltbot-integration
-        path: hindsight-integrations/moltbot/*.tgz
-        retention-days: 1
-
   release-control-plane:
     runs-on: ubuntu-latest
     environment: npm
@@ -415,7 +366,7 @@ jobs:
 
   create-github-release:
     runs-on: ubuntu-latest
-    needs: [release-python-packages, release-typescript-client, release-moltbot-integration, release-control-plane, release-rust-cli, release-docker-images, release-helm-chart]
+    needs: [release-python-packages, release-typescript-client, release-control-plane, release-rust-cli, release-docker-images, release-helm-chart]
     permissions:
       contents: write
 
@@ -438,12 +389,6 @@ jobs:
         name: typescript-client
         path: ./artifacts/typescript-client
 
-    - name: Download Moltbot Integration
-      uses: actions/download-artifact@v4
-      with:
-        name: moltbot-integration
-        path: ./artifacts/moltbot-integration
-
     - name: Download Control Plane
       uses: actions/download-artifact@v4
       with:
@@ -485,8 +430,6 @@ jobs:
         cp artifacts/python-packages/hindsight-embed/dist/* release-assets/ || true
         # TypeScript client
         cp artifacts/typescript-client/*.tgz release-assets/ || true
-        # Moltbot Integration
-        cp artifacts/moltbot-integration/*.tgz release-assets/ || true
         # Control Plane
         cp artifacts/control-plane/*.tgz release-assets/ || true
         # Rust CLI binaries

.github/workflows/test.yml

@@ -82,29 +82,6 @@ jobs:
     - name: Build TypeScript client
       run: npm run build --workspace=hindsight-clients/typescript
 
-  build-moltbot-integration:
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: '22'
-
-    - name: Install dependencies
-      working-directory: ./hindsight-integrations/moltbot
-      run: npm ci
-
-    - name: Run tests
-      working-directory: ./hindsight-integrations/moltbot
-      run: npm test
-
-    - name: Build
-      working-directory: ./hindsight-integrations/moltbot
-      run: npm run build
-
   build-control-plane:
     runs-on: ubuntu-latest
 

.gitignore

@@ -45,12 +45,9 @@ hindsight-docs/static/llms-full.txt
 
 hindsight-dev/benchmarks/locomo/results/
 hindsight-dev/benchmarks/longmemeval/results/
-hindsight-dev/benchmarks/consolidation/results/
-benchmarks/results/
 hindsight-cli/target
 hindsight-clients/rust/target
 .claude
 whats-next.md
 TASK.md
-# Changelog is now tracked in hindsight-docs/src/pages/changelog.md
-# CHANGELOG.md
+CHANGELOG.md

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.

README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-![Hindsight Banner](./hindsight-docs/static/img/hindsight-github-banner.png)
+![Hindsight Banner](./hindsight-docs/static/img/banner.svg)
 
 [Documentation](https://hindsight.vectorize.io) • [Paper](https://arxiv.org/abs/2512.12818) • [Cookbook](https://hindsight.vectorize.io/cookbook) • [Hindsight Cloud](https://vectorize.io/hindsight/cloud)
 
@@ -17,31 +17,55 @@
 
 ## What is Hindsight?
 
-Hindsight™ is an agent memory system built to create smarter agents that learn over time. Most agent memory systems focus on recalling conversation history. Hindsight is focused on making agents that learn, not just remember.
+Hindsight™ is an agent memory system built to create smarter agents that learn over time. It eliminates the shortcomings of alternative techniques such as RAG and knowledge graph and delivers state-of-the-art performance on long term memory tasks.
 
+Hindsight addresses common challenges that have frustrated AI engineers building agents to automate tasks and assist users with conversational interfaces. Many of these challenges stem directly from a lack of memory.
 
-<video src="https://github.com/user-attachments/assets/923b798d-3581-4897-bb62-9cfa5a931682" controls></video>
+- **Inconsistency:** Agents complete tasks successfully one time, then fail when asked to complete the same task again. Memory gives the agent a mechanism to remember what worked and what didn't and to use that information to reduce errors and improve consistency.
+- **Hallucinations:** Long term memory can be seeded with external knowledge to ground agent behavior in reliable sources to augment training data.
+- **Cognitive Overload:** As workflows get complex, retrievals, tool calls, user messages and agent responses can grow to fill the context window leading to context rot. Short term memory optimization allows agents to reduce tokens and focus context by removing irrelevant details.
 
-It eliminates the shortcomings of alternative techniques such as RAG and knowledge graph and delivers state-of-the-art performance on long term memory tasks.
+## How is Hindsight Different From Other Memory Systems?
+
+![Overview](./hindsight-docs/static/img/hindsight-overview.webp)
+
+Most agent memory implementation rely on basic vector search or sometimes use a knowledge graph. Hindsight uses biomimetic data structures to organize agent memories in a way that is more like how human memory works:
+
+- **World:** Facts about the world ("The stove gets hot")
+- **Experiences:** Agent's own experiences ("I touched the stove and it really hurt")
+- **Opinion:** Beliefs with confidence scores ("I shouldn't touch the stove again" - .99 confidence)
+- **Observation:** Complex mental models derived by reflecting on facts and experiences ("Curling irons, ovens, and fire are also hot. I shouldn't touch those either.")
+
+Memories in Hindsight are stored in banks (i.e. memory banks). When memories are added to Hindsight, they are pushed into either the world facts or experiences memory pathway. They are then represented as a combination of entities, relationships, and time series with sparse/dense vector representations to aid in later recall.
+
+Hindsight provides three simple methods to interact with the system:
+
+- **Retain:** Provide information to Hindsight that you want it to remember
+- **Recall:** Retrieve memories from Hindsight
+- **Reflect:** Reflect on memories and experiences to generate new observations and insights from existing memories.
+
+### Agent Memory That Learns
+
+A key goal of Hindsight is to build agent memory that enables agents to learn and improve over time. This is the role of the `reflect` operation which provides the agent to form broader opinions and observations over time.
+
+For example, imagine a product support agent that is helping a user troubleshoot a problem. It uses a `search-documentation` tool it found on an MCP server. Later in the conversation, the agent discovers that the documentation returned from the tool wasn't for the product the user was asking about. The agent now has an experience in its memory bank. And just like humans, we want that agent to learn from its experience.
+
+As the agent gains more experiences, `reflect` allows the agent to form observations about what worked, what didn't, and what to do differently the next time it encounters a similar task.
+
+---
 
 ## Memory Performance & Accuracy
 
-Hindsight is the most accurate agent memory system ever tested according to benchmark performance. It has achieved state-of-the-art performance on the LongMemEval benchmark, widely used to assess memory system performance across a variety of conversational AI scenarios. The current reported performance of Hindsight and other agent memory solutions as of January 2026 is shown here:
+Hindsight has achieved state-of-the-art performance on the LongMemEval benchmark, widely used to assess memory system performance across a variety of conversational
+AI scenarios. The current reported performance of Hindsight and other agent memory solutions as of December 2025 is shown here:
 
 ![Overview](./hindsight-docs/static/img/hindsight-bench.jpg)
 
-The benchmark performance data for Hindsight has been independently reproduced by research collaborators at the Virginia Tech [Sanghani Center for Artificial Intelligence and Data Analytics](https://sanghani.cs.vt.edu/) and The Washington Post. Other scores are self-reported by software vendors.
+The benchmark performance data for Hindsight and GPT-4o (full context) have been reproduced by research collaborators at the Virginia Tech [Sanghani Center for Artificial Intelligence and Data Analytics](https://sanghani.cs.vt.edu/) and The Washington Post. Other scores are self-reported by software vendors.
 
-Hindsight is being used in production at Fortune 500 enterprises and by a growing number of AI startups. 
-
-## Adding Hindsight to Your AI Agents
-
-The easiest way use Hindsight with an existing agent is with the LLM Wrapper. You can add memory to your agent with 2 lines of code. That will swap your current LLM client out with the Hindsight wrapper. After that, memories will be stored and retrieved automatically as you make LLM calls.
-
-If you need more control over how and when your agent stores and recalls memories, there's also a simple API you can integrate with using the SDKs or directly via HTTP.
-
-![Hindsight Banner](./hindsight-docs/static/img/migration-code.png)
+A thorough examination of the techniques implemented in Hindsight and detailed breakdowns of benchmark performance are [available on arXiv](https://arxiv.org/abs/2512.12818). This research is currently being prepared for conference submission and the wider peer review process.
 
+The benchmark results from this research can be inspected in our [visual benchmark explorer](https://hindsight-benchmarks.vercel.app). As additional improvements are made to Hindsight, new benchmark data will be available for review using this same tool.
 
 ## Quick Start
 
@@ -124,45 +148,8 @@ await client.recall('my-bank', 'What does Alice like?');
 
 ---
 
-## Use Cases
-
-
-Hindsight is built to support conversational AI agents as well as agents that are intended to perform tasks autonomously. The ideal use case for Hindsight are agents that require a blend of these features such as AI employees that need to handle open-ended tasks, change behavior based on user feedback, and learn to perform complex tasks to automate work at a level that approximates a human work. Hindsight can be used with simple AI workflows like those built with n8n and other similar tools, but may be overkill for such applications.
-
-### Per-User Memories and Chat History
-
-One of the simpler use cases you can use Hindsight for is to personalize AI chatbots and other conversational agents by storing and recalling memories associated with individual users.
-
-The requirements for this use case usually look something like this:
-
-![Per-User Memories](./hindsight-docs/static/img/per-user-memory-requirements.png)
-
-<video src="https://github.com/user-attachments/assets/4805e8e1-e7d1-47c6-a4f8-2344a5ec8906" controls></video>
-
-Satisfying these requirements in Hindsight is straightforward. When new user inputs and tool calls are ingested into Hindsight using the retain operation, custom metadata can be used to enrich the new memories. Metadata provides a convenient way to isolate memories that need to be restricted to a given user. Once these are fed into the retain operation, any raw memories and mental models that get created can be filtered when retrieving relevant memories. 
-
-![Per-User Memories](./hindsight-docs/static/img/per-user-memory-howto.png)
-
----
-
 ## Architecture & Operations
 
-![Overview](./hindsight-docs/static/img/hindsight-overview.webp)
-
-Most agent memory implementation rely on basic vector search or sometimes use a knowledge graph. Hindsight uses biomimetic data structures to organize agent memories in a way that is more like how human memory works:
-
-- **World:** Facts about the world ("The stove gets hot")
-- **Experiences:** Agent's own experiences ("I touched the stove and it really hurt")
-- **Mental Models:** Learned understanding of the agent's world formed by reflecting on raw memories and experiences.
-
-Memories in Hindsight are stored in banks (i.e. memory banks). When memories are added to Hindsight, they are pushed into either the world facts or experiences memory pathway. They are then represented as a combination of entities, relationships, and time series with sparse/dense vector representations to aid in later recall.
-
-Hindsight provides three simple methods to interact with the system:
-
-- **Retain:** Provide information to Hindsight that you want it to remember
-- **Recall:** Retrieve memories from Hindsight
-- **Reflect:** Reflect on memories and experiences to generate new observations and insights from existing memories.
-
 ### Retain
 
 The `retain` operation is used to push new memories into Hindsight. It tells Hindsight to _retain_ the information you pass in as an input.
@@ -221,7 +208,7 @@ The final output is trimmed as needed to fit within the token limit.
 
 ### Reflect
 
-The reflect operation is used to perform a more thorough analysis of existing memories. This allows the agent to form new connections between memories and build a more thorough understanding of its world.
+The reflect operation is used to perform a more thorough analysis of existing memories. This allows the agent to form new connections between memories which are then persisted as opinions and/or observations. When building agents, the reflect operation is a key capability to enable the agent to learn from its experiences. 
 
 For example, the `reflect` operation can be used to support use cases such as:
 

helm/hindsight/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: hindsight
 description: Hindsight helm chart
 type: application
-version: 0.4.2
-appVersion: "0.4.2"
+version: 0.3.0
+appVersion: "0.3.0"
 keywords:
   - ai
   - memory

hindsight-api/hindsight_api/__init__.py

@@ -46,4 +46,4 @@ __all__ = [
     "RemoteTEICrossEncoder",
     "LLMConfig",
 ]
-__version__ = "0.4.2"
+__version__ = "0.1.0"

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/http.py

@@ -92,7 +92,7 @@ class RecallRequest(BaseModel):
     query: str
     types: list[str] | None = Field(
         default=None,
-        description="List of fact types to recall: 'world', 'experience', 'observation'. Defaults to world and experience if not specified. "
+        description="List of fact types to recall: 'world', 'experience', 'mental_model'. Defaults to world and experience if not specified. "
         "Note: 'opinion' is accepted but ignored (opinions are excluded from recall).",
     )
     budget: Budget = Budget.MID
@@ -535,22 +535,6 @@ class ReflectFact(BaseModel):
     occurred_end: str | None = None
 
 
-class ReflectDirective(BaseModel):
-    """A directive applied during reflect."""
-
-    id: str = Field(description="Directive ID")
-    name: str = Field(description="Directive name")
-    content: str = Field(description="Directive content")
-
-
-class ReflectMentalModel(BaseModel):
-    """A mental model used during reflect."""
-
-    id: str = Field(description="Mental model ID")
-    text: str = Field(description="Mental model content")
-    context: str | None = Field(default=None, description="Additional context")
-
-
 class ReflectToolCall(BaseModel):
     """A tool call made during reflect agent execution."""
 
@@ -570,14 +554,22 @@ class ReflectLLMCall(BaseModel):
     duration_ms: int = Field(description="Execution time in milliseconds")
 
 
+class ReflectMentalModel(BaseModel):
+    """A mental model accessed during reflect."""
+
+    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, directive")
+    observations: list[str] | None = Field(
+        default=None, description="Observations for directive mental models (subtype='directive')"
+    )
+
+
 class ReflectBasedOn(BaseModel):
-    """Evidence the response is based on: memories, mental models, and directives."""
+    """Evidence the response is based on: memories and mental models."""
 
     memories: list[ReflectFact] = Field(default_factory=list, description="Memory facts used to generate the response")
-    mental_models: list[ReflectMentalModel] = Field(
-        default_factory=list, description="Mental models used during reflection"
-    )
-    directives: list[ReflectDirective] = Field(default_factory=list, description="Directives applied during reflection")
 
 
 class ReflectTrace(BaseModel):
@@ -585,6 +577,10 @@ class ReflectTrace(BaseModel):
 
     tool_calls: list[ReflectToolCall] = Field(default_factory=list, description="Tool calls made during reflection")
     llm_calls: list[ReflectLLMCall] = Field(default_factory=list, description="LLM calls made during reflection")
+    mental_models: list[ReflectMentalModel] = Field(
+        default_factory=list,
+        description="Mental models used during reflection (includes directives with subtype='directive')",
+    )
 
 
 class ReflectResponse(BaseModel):
@@ -599,6 +595,15 @@ class ReflectResponse(BaseModel):
                         {"id": "123", "text": "AI is used in healthcare", "type": "world"},
                         {"id": "456", "text": "I discussed AI applications last week", "type": "experience"},
                     ],
+                    "mental_models": [
+                        {
+                            "id": "mm-1",
+                            "name": "AI Technology",
+                            "type": "concept",
+                            "subtype": "structural",
+                            "description": "Understanding of AI capabilities",
+                        }
+                    ],
                 },
                 "structured_output": {
                     "summary": "AI is transformative",
@@ -608,14 +613,6 @@ class ReflectResponse(BaseModel):
                 "trace": {
                     "tool_calls": [{"tool": "recall", "input": {"query": "AI"}, "duration_ms": 150}],
                     "llm_calls": [{"scope": "agent_1", "duration_ms": 1200}],
-                    "observations": [
-                        {
-                            "id": "obs-1",
-                            "name": "AI Technology",
-                            "type": "concept",
-                            "subtype": "structural",
-                        }
-                    ],
                 },
             }
         }
@@ -1019,7 +1016,7 @@ class BankStatsResponse(BaseModel):
                 "failed_operations": 0,
                 "last_consolidated_at": "2024-01-15T10:30:00Z",
                 "pending_consolidation": 0,
-                "total_observations": 45,
+                "total_mental_models": 45,
             }
         }
     )
@@ -1036,8 +1033,8 @@ class BankStatsResponse(BaseModel):
     failed_operations: int
     # Consolidation stats
     last_consolidated_at: str | None = Field(default=None, description="When consolidation last ran (ISO format)")
-    pending_consolidation: int = Field(default=0, description="Number of memories not yet processed into observations")
-    total_observations: int = Field(default=0, description="Total number of observations")
+    pending_consolidation: int = Field(default=0, description="Number of memories not yet processed into mental models")
+    total_mental_models: int = Field(default=0, description="Total number of mental models")
 
 
 # Mental Model models
@@ -1098,21 +1095,12 @@ class UpdateDirectiveRequest(BaseModel):
 
 
 # =========================================================================
-# Mental Models (stored reflect responses)
+# Reflections Models
 # =========================================================================
 
 
-class MentalModelTrigger(BaseModel):
-    """Trigger settings for a mental model."""
-
-    refresh_after_consolidation: bool = Field(
-        default=False,
-        description="If true, refresh this mental model after observations consolidation (real-time mode)",
-    )
-
-
-class MentalModelResponse(BaseModel):
-    """Response model for a mental model (stored reflect response)."""
+class ReflectionResponse(BaseModel):
+    """Response model for a reflection."""
 
     id: str
     bank_id: str
@@ -1120,24 +1108,22 @@ class MentalModelResponse(BaseModel):
     source_query: str
     content: str
     tags: list[str] = Field(default_factory=list)
-    max_tokens: int = Field(default=2048)
-    trigger: MentalModelTrigger = Field(default_factory=MentalModelTrigger)
     last_refreshed_at: str | None = None
     created_at: str | None = None
     reflect_response: dict | None = Field(
         default=None,
-        description="Full reflect API response payload including based_on facts and observations",
+        description="Full reflect API response payload including based_on facts and mental_models",
     )
 
 
-class MentalModelListResponse(BaseModel):
-    """Response model for listing mental models."""
+class ReflectionListResponse(BaseModel):
+    """Response model for listing reflections."""
 
-    items: list[MentalModelResponse]
+    items: list[ReflectionResponse]
 
 
-class CreateMentalModelRequest(BaseModel):
-    """Request model for creating a mental model."""
+class CreateReflectionRequest(BaseModel):
+    """Request model for creating a reflection."""
 
     model_config = ConfigDict(
         json_schema_extra={
@@ -1146,44 +1132,34 @@ class CreateMentalModelRequest(BaseModel):
                 "source_query": "How does the team prefer to communicate?",
                 "tags": ["team"],
                 "max_tokens": 2048,
-                "trigger": {"refresh_after_consolidation": False},
             }
         }
     )
 
-    name: str = Field(description="Human-readable name for the mental model")
+    name: str = Field(description="Human-readable name for the reflection")
     source_query: str = Field(description="The query to run to generate content")
     tags: list[str] = Field(default_factory=list, description="Tags for scoped visibility")
     max_tokens: int = Field(default=2048, ge=256, le=8192, description="Maximum tokens for generated content")
-    trigger: MentalModelTrigger = Field(default_factory=MentalModelTrigger, description="Trigger settings")
 
 
-class CreateMentalModelResponse(BaseModel):
-    """Response model for mental model creation."""
+class CreateReflectionResponse(BaseModel):
+    """Response model for reflection creation."""
 
     operation_id: str = Field(description="Operation ID to track progress")
 
 
-class UpdateMentalModelRequest(BaseModel):
-    """Request model for updating a mental model."""
+class UpdateReflectionRequest(BaseModel):
+    """Request model for updating a reflection."""
 
     model_config = ConfigDict(
         json_schema_extra={
             "example": {
                 "name": "Updated Team Communication Preferences",
-                "source_query": "How does the team prefer to communicate?",
-                "max_tokens": 4096,
-                "tags": ["team", "communication"],
-                "trigger": {"refresh_after_consolidation": True},
             }
         }
     )
 
-    name: str | None = Field(default=None, description="New name for the mental model")
-    source_query: str | None = Field(default=None, description="New source query for the mental model")
-    max_tokens: int | None = Field(default=None, ge=256, le=8192, description="Maximum tokens for generated content")
-    tags: list[str] | None = Field(default=None, description="Tags for scoped visibility")
-    trigger: MentalModelTrigger | None = Field(default=None, description="Trigger settings")
+    name: str | None = Field(default=None, description="New name for the reflection")
 
 
 class OperationResponse(BaseModel):
@@ -1312,7 +1288,7 @@ class AsyncOperationSubmitResponse(BaseModel):
 class FeaturesInfo(BaseModel):
     """Feature flags indicating which capabilities are enabled."""
 
-    observations: bool = Field(description="Whether observations (auto-consolidation) are enabled")
+    mental_models: bool = Field(description="Whether mental models (auto-consolidation) are enabled")
     mcp: bool = Field(description="Whether MCP (Model Context Protocol) server is enabled")
     worker: bool = Field(description="Whether the background worker is enabled")
 
@@ -1323,9 +1299,9 @@ class VersionResponse(BaseModel):
     model_config = ConfigDict(
         json_schema_extra={
             "example": {
-                "api_version": "0.4.0",
+                "api_version": "1.0.0",
                 "features": {
-                    "observations": False,
+                    "mental_models": False,
                     "mcp": True,
                     "worker": True,
                 },
@@ -1414,7 +1390,6 @@ def create_app(
                 poll_interval_ms=config.worker_poll_interval_ms,
                 batch_size=config.worker_batch_size,
                 max_retries=config.worker_max_retries,
-                tenant_extension=getattr(memory, "_tenant_extension", None),
             )
             poller_task = asyncio.create_task(poller.run())
             logging.info(f"Worker poller started (worker_id={worker_id})")
@@ -1567,14 +1542,13 @@ def _register_routes(app: FastAPI):
         Returns version info and feature flags that can be used by clients
         to determine which capabilities are available.
         """
-        from hindsight_api import __version__
         from hindsight_api.config import get_config
 
         config = get_config()
         return VersionResponse(
-            api_version=__version__,
+            api_version="1.0.0",
             features=FeaturesInfo(
-                observations=config.enable_observations,
+                mental_models=config.enable_mental_models,
                 mcp=config.mcp_enabled,
                 worker=config.worker_enabled,
             ),
@@ -1888,48 +1862,25 @@ def _register_routes(app: FastAPI):
                     tags_match=request.tags_match,
                 )
 
-            # Build based_on (memories + mental_models + directives) if facts are requested
+            # Build based_on (memories + mental_models) if facts are requested
             based_on_result: ReflectBasedOn | None = None
             if request.include.facts is not None:
                 memories = []
-                mental_models = []
-                directives = []
                 for fact_type, facts in core_result.based_on.items():
-                    if fact_type == "directives":
-                        # Directives have different structure (id, name, content)
-                        for directive in facts:
-                            directives.append(
-                                ReflectDirective(
-                                    id=directive.id,
-                                    name=directive.name,
-                                    content=directive.content,
-                                )
+                    for fact in facts:
+                        memories.append(
+                            ReflectFact(
+                                id=fact.id,
+                                text=fact.text,
+                                type=fact.fact_type,
+                                context=fact.context,
+                                occurred_start=fact.occurred_start,
+                                occurred_end=fact.occurred_end,
                             )
-                    elif fact_type == "mental_models":
-                        # Mental models are MemoryFact with type "mental_models"
-                        for fact in facts:
-                            mental_models.append(
-                                ReflectMentalModel(
-                                    id=fact.id,
-                                    text=fact.text,
-                                    context=fact.context,
-                                )
-                            )
-                    else:
-                        for fact in facts:
-                            memories.append(
-                                ReflectFact(
-                                    id=fact.id,
-                                    text=fact.text,
-                                    type=fact.fact_type,
-                                    context=fact.context,
-                                    occurred_start=fact.occurred_start,
-                                    occurred_end=fact.occurred_end,
-                                )
-                            )
-                based_on_result = ReflectBasedOn(memories=memories, mental_models=mental_models, directives=directives)
+                        )
+                based_on_result = ReflectBasedOn(memories=memories)
 
-            # Build trace (tool_calls + llm_calls + observations) if tool_calls is requested
+            # Build trace (tool_calls + llm_calls + mental_models) if tool_calls is requested
             trace_result: ReflectTrace | None = None
             if request.include.tool_calls is not None:
                 include_output = request.include.tool_calls.output
@@ -1944,9 +1895,33 @@ def _register_routes(app: FastAPI):
                     for tc in core_result.tool_trace
                 ]
                 llm_calls = [ReflectLLMCall(scope=lc.scope, duration_ms=lc.duration_ms) for lc in core_result.llm_trace]
+                # Build map of directive observations by id
+                directive_observations = {d.id: d.rules for d in core_result.directives_applied}
+                # Build mental models from tool trace (get_mental_model outputs)
+                trace_mental_models: list[ReflectMentalModel] = []
+                seen_model_ids: set[str] = set()
+                for tc in core_result.tool_trace:
+                    if tc.tool == "get_mental_model" and tc.output.get("found") and "model" in tc.output:
+                        model = tc.output["model"]
+                        model_id = model.get("id")
+                        if model_id and model_id not in seen_model_ids:
+                            seen_model_ids.add(model_id)
+                            model_subtype = model.get("subtype", "structural")
+                            trace_mental_models.append(
+                                ReflectMentalModel(
+                                    id=model_id,
+                                    name=model.get("name", ""),
+                                    type=model.get("type", "concept"),
+                                    subtype=model_subtype,
+                                    observations=directive_observations.get(model_id)
+                                    if model_subtype == "directive"
+                                    else None,
+                                )
+                            )
                 trace_result = ReflectTrace(
                     tool_calls=tool_calls,
                     llm_calls=llm_calls,
+                    mental_models=trace_mental_models,
                 )
 
             return ReflectResponse(
@@ -2094,16 +2069,16 @@ def _register_routes(app: FastAPI):
                 last_consolidated_at = consolidation_stats["last_consolidated_at"] if consolidation_stats else None
                 pending_consolidation = consolidation_stats["pending"] if consolidation_stats else 0
 
-                # Count total observations (consolidated knowledge)
-                observation_count_result = await conn.fetchrow(
+                # Count total mental models
+                mental_model_count_result = await conn.fetchrow(
                     f"""
                     SELECT COUNT(*) as count
                     FROM {fq_table("memory_units")}
-                    WHERE bank_id = $1 AND fact_type = 'observation'
+                    WHERE bank_id = $1 AND fact_type = 'mental_model'
                     """,
                     bank_id,
                 )
-                total_observations = observation_count_result["count"] if observation_count_result else 0
+                total_mental_models = mental_model_count_result["count"] if mental_model_count_result else 0
 
                 # Format results
                 nodes_by_type = {row["fact_type"]: row["count"] for row in node_stats}
@@ -2136,7 +2111,7 @@ def _register_routes(app: FastAPI):
                     failed_operations=failed_operations,
                     last_consolidated_at=(last_consolidated_at.isoformat() if last_consolidated_at else None),
                     pending_consolidation=pending_consolidation,
-                    total_observations=total_observations,
+                    total_mental_models=total_mental_models,
                 )
 
         except (AuthenticationError, HTTPException):
@@ -2243,18 +2218,18 @@ def _register_routes(app: FastAPI):
 
     # =========================================================================
     # =========================================================================
-    # MENTAL MODELS ENDPOINTS (stored reflect responses)
+    # REFLECTIONS ENDPOINTS
     # =========================================================================
 
     @app.get(
-        "/v1/default/banks/{bank_id}/mental-models",
-        response_model=MentalModelListResponse,
-        summary="List mental models",
+        "/v1/default/banks/{bank_id}/reflections",
+        response_model=ReflectionListResponse,
+        summary="List reflections",
         description="List user-curated living documents that stay current.",
-        operation_id="list_mental_models",
-        tags=["Mental Models"],
+        operation_id="list_reflections",
+        tags=["Reflections"],
     )
-    async def api_list_mental_models(
+    async def api_list_reflections(
         bank_id: str,
         tags_filter: list[str] | None = Query(None, alias="tags", description="Filter by tags"),
         tags_match: Literal["any", "all", "exact"] = Query("any", description="How to match tags"),
@@ -2262,9 +2237,9 @@ def _register_routes(app: FastAPI):
         offset: int = Query(0, ge=0),
         request_context: RequestContext = Depends(get_request_context),
     ):
-        """List mental models for a bank."""
+        """List reflections for a bank."""
         try:
-            mental_models = await app.state.memory.list_mental_models(
+            reflections = await app.state.memory.list_reflections(
                 bank_id=bank_id,
                 tags=tags_filter,
                 tags_match=tags_match,
@@ -2272,83 +2247,74 @@ def _register_routes(app: FastAPI):
                 offset=offset,
                 request_context=request_context,
             )
-            return MentalModelListResponse(items=[MentalModelResponse(**m) for m in mental_models])
+            return ReflectionListResponse(items=[ReflectionResponse(**r) for r in reflections])
         except (AuthenticationError, HTTPException):
             raise
         except Exception as e:
             import traceback
 
             error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
-            logger.error(f"Error in GET /v1/default/banks/{bank_id}/mental-models: {error_detail}")
+            logger.error(f"Error in GET /v1/default/banks/{bank_id}/reflections: {error_detail}")
             raise HTTPException(status_code=500, detail=str(e))
 
     @app.get(
-        "/v1/default/banks/{bank_id}/mental-models/{mental_model_id}",
-        response_model=MentalModelResponse,
-        summary="Get mental model",
-        description="Get a specific mental model by ID.",
-        operation_id="get_mental_model",
-        tags=["Mental Models"],
+        "/v1/default/banks/{bank_id}/reflections/{reflection_id}",
+        response_model=ReflectionResponse,
+        summary="Get reflection",
+        description="Get a specific reflection by ID.",
+        operation_id="get_reflection",
+        tags=["Reflections"],
     )
-    async def api_get_mental_model(
+    async def api_get_reflection(
         bank_id: str,
-        mental_model_id: str,
+        reflection_id: str,
         request_context: RequestContext = Depends(get_request_context),
     ):
-        """Get a mental model by ID."""
+        """Get a reflection by ID."""
         try:
-            mental_model = await app.state.memory.get_mental_model(
+            reflection = await app.state.memory.get_reflection(
                 bank_id=bank_id,
-                mental_model_id=mental_model_id,
+                reflection_id=reflection_id,
                 request_context=request_context,
             )
-            if mental_model is None:
-                raise HTTPException(status_code=404, detail=f"Mental model '{mental_model_id}' not found")
-            return MentalModelResponse(**mental_model)
+            if reflection is None:
+                raise HTTPException(status_code=404, detail=f"Reflection '{reflection_id}' not found")
+            return ReflectionResponse(**reflection)
         except (AuthenticationError, HTTPException):
             raise
         except Exception as e:
             import traceback
 
             error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
-            logger.error(f"Error in GET /v1/default/banks/{bank_id}/mental-models/{mental_model_id}: {error_detail}")
+            logger.error(f"Error in GET /v1/default/banks/{bank_id}/reflections/{reflection_id}: {error_detail}")
             raise HTTPException(status_code=500, detail=str(e))
 
     @app.post(
-        "/v1/default/banks/{bank_id}/mental-models",
-        response_model=CreateMentalModelResponse,
-        summary="Create mental model",
-        description="Create a mental model by running reflect with the source query in the background. "
+        "/v1/default/banks/{bank_id}/reflections",
+        response_model=CreateReflectionResponse,
+        summary="Create reflection",
+        description="Create a reflection by running reflect with the source query in the background. "
         "Returns an operation ID to track progress. The content is auto-generated by the reflect endpoint. "
         "Use the operations endpoint to check completion status.",
-        operation_id="create_mental_model",
-        tags=["Mental Models"],
+        operation_id="create_reflection",
+        tags=["Reflections"],
     )
-    async def api_create_mental_model(
+    async def api_create_reflection(
         bank_id: str,
-        body: CreateMentalModelRequest,
+        body: CreateReflectionRequest,
         request_context: RequestContext = Depends(get_request_context),
     ):
-        """Create a mental model (async - returns operation_id)."""
+        """Create a reflection (async - returns operation_id)."""
         try:
-            # 1. Create the mental model with placeholder content
-            mental_model = await app.state.memory.create_mental_model(
+            result = await app.state.memory.submit_async_create_reflection(
                 bank_id=bank_id,
                 name=body.name,
                 source_query=body.source_query,
-                content="Generating content...",
                 tags=body.tags if body.tags else None,
                 max_tokens=body.max_tokens,
-                trigger=body.trigger.model_dump() if body.trigger else None,
                 request_context=request_context,
             )
-            # 2. Schedule a refresh to generate the actual content
-            result = await app.state.memory.submit_async_refresh_mental_model(
-                bank_id=bank_id,
-                mental_model_id=mental_model["id"],
-                request_context=request_context,
-            )
-            return CreateMentalModelResponse(operation_id=result["operation_id"])
+            return CreateReflectionResponse(operation_id=result["operation_id"])
         except ValueError as e:
             raise HTTPException(status_code=400, detail=str(e))
         except (AuthenticationError, HTTPException):
@@ -2357,27 +2323,27 @@ def _register_routes(app: FastAPI):
             import traceback
 
             error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
-            logger.error(f"Error in POST /v1/default/banks/{bank_id}/mental-models: {error_detail}")
+            logger.error(f"Error in POST /v1/default/banks/{bank_id}/reflections: {error_detail}")
             raise HTTPException(status_code=500, detail=str(e))
 
     @app.post(
-        "/v1/default/banks/{bank_id}/mental-models/{mental_model_id}/refresh",
+        "/v1/default/banks/{bank_id}/reflections/{reflection_id}/refresh",
         response_model=AsyncOperationSubmitResponse,
-        summary="Refresh mental model",
+        summary="Refresh reflection",
         description="Submit an async task to re-run the source query through reflect and update the content.",
-        operation_id="refresh_mental_model",
-        tags=["Mental Models"],
+        operation_id="refresh_reflection",
+        tags=["Reflections"],
     )
-    async def api_refresh_mental_model(
+    async def api_refresh_reflection(
         bank_id: str,
-        mental_model_id: str,
+        reflection_id: str,
         request_context: RequestContext = Depends(get_request_context),
     ):
-        """Refresh a mental model by re-running its source query (async)."""
+        """Refresh a reflection by re-running its source query (async)."""
         try:
-            result = await app.state.memory.submit_async_refresh_mental_model(
+            result = await app.state.memory.submit_async_refresh_reflection(
                 bank_id=bank_id,
-                mental_model_id=mental_model_id,
+                reflection_id=reflection_id,
                 request_context=request_context,
             )
             return AsyncOperationSubmitResponse(operation_id=result["operation_id"], status="queued")
@@ -2390,69 +2356,65 @@ def _register_routes(app: FastAPI):
 
             error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
             logger.error(
-                f"Error in POST /v1/default/banks/{bank_id}/mental-models/{mental_model_id}/refresh: {error_detail}"
+                f"Error in POST /v1/default/banks/{bank_id}/reflections/{reflection_id}/refresh: {error_detail}"
             )
             raise HTTPException(status_code=500, detail=str(e))
 
     @app.patch(
-        "/v1/default/banks/{bank_id}/mental-models/{mental_model_id}",
-        response_model=MentalModelResponse,
-        summary="Update mental model",
-        description="Update a mental model's name and/or source query.",
-        operation_id="update_mental_model",
-        tags=["Mental Models"],
+        "/v1/default/banks/{bank_id}/reflections/{reflection_id}",
+        response_model=ReflectionResponse,
+        summary="Update reflection",
+        description="Update a reflection's name.",
+        operation_id="update_reflection",
+        tags=["Reflections"],
     )
-    async def api_update_mental_model(
+    async def api_update_reflection(
         bank_id: str,
-        mental_model_id: str,
-        body: UpdateMentalModelRequest,
+        reflection_id: str,
+        body: UpdateReflectionRequest,
         request_context: RequestContext = Depends(get_request_context),
     ):
-        """Update a mental model."""
+        """Update a reflection."""
         try:
-            mental_model = await app.state.memory.update_mental_model(
+            reflection = await app.state.memory.update_reflection(
                 bank_id=bank_id,
-                mental_model_id=mental_model_id,
+                reflection_id=reflection_id,
                 name=body.name,
-                source_query=body.source_query,
-                max_tokens=body.max_tokens,
-                tags=body.tags,
-                trigger=body.trigger.model_dump() if body.trigger else None,
                 request_context=request_context,
             )
-            if mental_model is None:
-                raise HTTPException(status_code=404, detail=f"Mental model '{mental_model_id}' not found")
-            return MentalModelResponse(**mental_model)
+            if reflection is None:
+                raise HTTPException(status_code=404, detail=f"Reflection '{reflection_id}' not found")
+            return ReflectionResponse(**reflection)
         except (AuthenticationError, HTTPException):
             raise
         except Exception as e:
             import traceback
 
             error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
-            logger.error(f"Error in PATCH /v1/default/banks/{bank_id}/mental-models/{mental_model_id}: {error_detail}")
+            logger.error(f"Error in PATCH /v1/default/banks/{bank_id}/reflections/{reflection_id}: {error_detail}")
             raise HTTPException(status_code=500, detail=str(e))
 
     @app.delete(
-        "/v1/default/banks/{bank_id}/mental-models/{mental_model_id}",
-        summary="Delete mental model",
-        description="Delete a mental model.",
-        operation_id="delete_mental_model",
-        tags=["Mental Models"],
+        "/v1/default/banks/{bank_id}/reflections/{reflection_id}",
+        summary="Delete reflection",
+        description="Delete a reflection.",
+        operation_id="delete_reflection",
+        tags=["Reflections"],
     )
-    async def api_delete_mental_model(
+    async def api_delete_reflection(
         bank_id: str,
-        mental_model_id: str,
+        reflection_id: str,
         request_context: RequestContext = Depends(get_request_context),
     ):
-        """Delete a mental model."""
+        """Delete a reflection."""
         try:
-            deleted = await app.state.memory.delete_mental_model(
+            deleted = await app.state.memory.delete_reflection(
                 bank_id=bank_id,
-                mental_model_id=mental_model_id,
+                reflection_id=reflection_id,
                 request_context=request_context,
             )
             if not deleted:
-                raise HTTPException(status_code=404, detail=f"Mental model '{mental_model_id}' not found")
+                raise HTTPException(status_code=404, detail=f"Reflection '{reflection_id}' not found")
             return {"status": "deleted"}
         except (AuthenticationError, HTTPException):
             raise
@@ -2460,7 +2422,7 @@ def _register_routes(app: FastAPI):
             import traceback
 
             error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
-            logger.error(f"Error in DELETE /v1/default/banks/{bank_id}/mental-models/{mental_model_id}: {error_detail}")
+            logger.error(f"Error in DELETE /v1/default/banks/{bank_id}/reflections/{reflection_id}: {error_detail}")
             raise HTTPException(status_code=500, detail=str(e))
 
     # =========================================================================
@@ -3184,20 +3146,20 @@ def _register_routes(app: FastAPI):
             raise HTTPException(status_code=500, detail=str(e))
 
     @app.delete(
-        "/v1/default/banks/{bank_id}/observations",
+        "/v1/default/banks/{bank_id}/mental-models",
         response_model=DeleteResponse,
-        summary="Clear all observations",
-        description="Delete all observations for a memory bank. This is useful for resetting the consolidated knowledge.",
-        operation_id="clear_observations",
+        summary="Clear all mental models",
+        description="Delete all mental models for a memory bank. This is useful for resetting the consolidated knowledge.",
+        operation_id="clear_mental_models",
         tags=["Banks"],
     )
-    async def api_clear_observations(bank_id: str, request_context: RequestContext = Depends(get_request_context)):
-        """Clear all observations for a bank."""
+    async def api_clear_mental_models(bank_id: str, request_context: RequestContext = Depends(get_request_context)):
+        """Clear all mental models for a bank."""
         try:
-            result = await app.state.memory.clear_observations(bank_id, request_context=request_context)
+            result = await app.state.memory.clear_mental_models(bank_id, request_context=request_context)
             return DeleteResponse(
                 success=True,
-                message=f"Cleared {result.get('deleted_count', 0)} observations",
+                message=f"Cleared {result.get('deleted_count', 0)} mental models",
                 deleted_count=result.get("deleted_count", 0),
             )
         except (AuthenticationError, HTTPException):
@@ -3206,14 +3168,14 @@ def _register_routes(app: FastAPI):
             import traceback
 
             error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
-            logger.error(f"Error in DELETE /v1/default/banks/{bank_id}/observations: {error_detail}")
+            logger.error(f"Error in DELETE /v1/default/banks/{bank_id}/mental-models: {error_detail}")
             raise HTTPException(status_code=500, detail=str(e))
 
     @app.post(
         "/v1/default/banks/{bank_id}/consolidate",
         response_model=ConsolidationResponse,
         summary="Trigger consolidation",
-        description="Run memory consolidation to create/update observations from recent memories.",
+        description="Run memory consolidation to create/update mental models from recent memories.",
         operation_id="trigger_consolidation",
         tags=["Banks"],
     )

hindsight-api/hindsight_api/config.py

@@ -20,15 +20,11 @@ logger = logging.getLogger(__name__)
 
 # Environment variable names
 ENV_DATABASE_URL = "HINDSIGHT_API_DATABASE_URL"
-ENV_DATABASE_SCHEMA = "HINDSIGHT_API_DATABASE_SCHEMA"
 ENV_LLM_PROVIDER = "HINDSIGHT_API_LLM_PROVIDER"
 ENV_LLM_API_KEY = "HINDSIGHT_API_LLM_API_KEY"
 ENV_LLM_MODEL = "HINDSIGHT_API_LLM_MODEL"
 ENV_LLM_BASE_URL = "HINDSIGHT_API_LLM_BASE_URL"
 ENV_LLM_MAX_CONCURRENT = "HINDSIGHT_API_LLM_MAX_CONCURRENT"
-ENV_LLM_MAX_RETRIES = "HINDSIGHT_API_LLM_MAX_RETRIES"
-ENV_LLM_INITIAL_BACKOFF = "HINDSIGHT_API_LLM_INITIAL_BACKOFF"
-ENV_LLM_MAX_BACKOFF = "HINDSIGHT_API_LLM_MAX_BACKOFF"
 ENV_LLM_TIMEOUT = "HINDSIGHT_API_LLM_TIMEOUT"
 ENV_LLM_GROQ_SERVICE_TIER = "HINDSIGHT_API_LLM_GROQ_SERVICE_TIER"
 
@@ -37,35 +33,19 @@ ENV_RETAIN_LLM_PROVIDER = "HINDSIGHT_API_RETAIN_LLM_PROVIDER"
 ENV_RETAIN_LLM_API_KEY = "HINDSIGHT_API_RETAIN_LLM_API_KEY"
 ENV_RETAIN_LLM_MODEL = "HINDSIGHT_API_RETAIN_LLM_MODEL"
 ENV_RETAIN_LLM_BASE_URL = "HINDSIGHT_API_RETAIN_LLM_BASE_URL"
-ENV_RETAIN_LLM_MAX_CONCURRENT = "HINDSIGHT_API_RETAIN_LLM_MAX_CONCURRENT"
-ENV_RETAIN_LLM_MAX_RETRIES = "HINDSIGHT_API_RETAIN_LLM_MAX_RETRIES"
-ENV_RETAIN_LLM_INITIAL_BACKOFF = "HINDSIGHT_API_RETAIN_LLM_INITIAL_BACKOFF"
-ENV_RETAIN_LLM_MAX_BACKOFF = "HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF"
-ENV_RETAIN_LLM_TIMEOUT = "HINDSIGHT_API_RETAIN_LLM_TIMEOUT"
 
 ENV_REFLECT_LLM_PROVIDER = "HINDSIGHT_API_REFLECT_LLM_PROVIDER"
 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_REFLECT_LLM_MAX_CONCURRENT = "HINDSIGHT_API_REFLECT_LLM_MAX_CONCURRENT"
-ENV_REFLECT_LLM_MAX_RETRIES = "HINDSIGHT_API_REFLECT_LLM_MAX_RETRIES"
-ENV_REFLECT_LLM_INITIAL_BACKOFF = "HINDSIGHT_API_REFLECT_LLM_INITIAL_BACKOFF"
-ENV_REFLECT_LLM_MAX_BACKOFF = "HINDSIGHT_API_REFLECT_LLM_MAX_BACKOFF"
-ENV_REFLECT_LLM_TIMEOUT = "HINDSIGHT_API_REFLECT_LLM_TIMEOUT"
 
 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_CONSOLIDATION_LLM_MAX_CONCURRENT = "HINDSIGHT_API_CONSOLIDATION_LLM_MAX_CONCURRENT"
-ENV_CONSOLIDATION_LLM_MAX_RETRIES = "HINDSIGHT_API_CONSOLIDATION_LLM_MAX_RETRIES"
-ENV_CONSOLIDATION_LLM_INITIAL_BACKOFF = "HINDSIGHT_API_CONSOLIDATION_LLM_INITIAL_BACKOFF"
-ENV_CONSOLIDATION_LLM_MAX_BACKOFF = "HINDSIGHT_API_CONSOLIDATION_LLM_MAX_BACKOFF"
-ENV_CONSOLIDATION_LLM_TIMEOUT = "HINDSIGHT_API_CONSOLIDATION_LLM_TIMEOUT"
 
 ENV_EMBEDDINGS_PROVIDER = "HINDSIGHT_API_EMBEDDINGS_PROVIDER"
 ENV_EMBEDDINGS_LOCAL_MODEL = "HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL"
-ENV_EMBEDDINGS_LOCAL_FORCE_CPU = "HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU"
 ENV_EMBEDDINGS_TEI_URL = "HINDSIGHT_API_EMBEDDINGS_TEI_URL"
 ENV_EMBEDDINGS_OPENAI_API_KEY = "HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY"
 ENV_EMBEDDINGS_OPENAI_MODEL = "HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL"
@@ -85,7 +65,6 @@ ENV_RERANKER_LITELLM_MODEL = "HINDSIGHT_API_RERANKER_LITELLM_MODEL"
 
 ENV_RERANKER_PROVIDER = "HINDSIGHT_API_RERANKER_PROVIDER"
 ENV_RERANKER_LOCAL_MODEL = "HINDSIGHT_API_RERANKER_LOCAL_MODEL"
-ENV_RERANKER_LOCAL_FORCE_CPU = "HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU"
 ENV_RERANKER_LOCAL_MAX_CONCURRENT = "HINDSIGHT_API_RERANKER_LOCAL_MAX_CONCURRENT"
 ENV_RERANKER_TEI_URL = "HINDSIGHT_API_RERANKER_TEI_URL"
 ENV_RERANKER_TEI_BATCH_SIZE = "HINDSIGHT_API_RERANKER_TEI_BATCH_SIZE"
@@ -108,23 +87,21 @@ 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"
 
-# Vertex AI configuration
-ENV_LLM_VERTEXAI_PROJECT_ID = "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID"
-ENV_LLM_VERTEXAI_REGION = "HINDSIGHT_API_LLM_VERTEXAI_REGION"
-ENV_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY = "HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY"
+# 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"
+# Mental models settings
+ENV_ENABLE_MENTAL_MODELS = "HINDSIGHT_API_ENABLE_MENTAL_MODELS"
+ENV_CONSOLIDATION_SIMILARITY_THRESHOLD = "HINDSIGHT_API_CONSOLIDATION_SIMILARITY_THRESHOLD"
 ENV_CONSOLIDATION_BATCH_SIZE = "HINDSIGHT_API_CONSOLIDATION_BATCH_SIZE"
-ENV_CONSOLIDATION_MAX_TOKENS = "HINDSIGHT_API_CONSOLIDATION_MAX_TOKENS"
 
 # Optimization flags
 ENV_SKIP_LLM_VERIFICATION = "HINDSIGHT_API_SKIP_LLM_VERIFICATION"
@@ -152,29 +129,18 @@ ENV_REFLECT_MAX_ITERATIONS = "HINDSIGHT_API_REFLECT_MAX_ITERATIONS"
 
 # Default values
 DEFAULT_DATABASE_URL = "pg0"
-DEFAULT_DATABASE_SCHEMA = "public"
 DEFAULT_LLM_PROVIDER = "openai"
 DEFAULT_LLM_MODEL = "gpt-5-mini"
 DEFAULT_LLM_MAX_CONCURRENT = 32
-DEFAULT_LLM_MAX_RETRIES = 10  # Max retry attempts for LLM API calls
-DEFAULT_LLM_INITIAL_BACKOFF = 1.0  # Initial backoff in seconds for retry exponential backoff
-DEFAULT_LLM_MAX_BACKOFF = 60.0  # Max backoff cap in seconds for retry exponential backoff
 DEFAULT_LLM_TIMEOUT = 120.0  # seconds
 
-# Vertex AI defaults
-DEFAULT_LLM_VERTEXAI_PROJECT_ID = None  # Required for Vertex AI
-DEFAULT_LLM_VERTEXAI_REGION = "us-central1"
-DEFAULT_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY = None  # Optional, uses ADC if not set
-
 DEFAULT_EMBEDDINGS_PROVIDER = "local"
 DEFAULT_EMBEDDINGS_LOCAL_MODEL = "BAAI/bge-small-en-v1.5"
-DEFAULT_EMBEDDINGS_LOCAL_FORCE_CPU = False  # Force CPU mode for local embeddings (avoids MPS/XPC issues on macOS)
 DEFAULT_EMBEDDINGS_OPENAI_MODEL = "text-embedding-3-small"
 DEFAULT_EMBEDDING_DIMENSION = 384
 
 DEFAULT_RERANKER_PROVIDER = "local"
 DEFAULT_RERANKER_LOCAL_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2"
-DEFAULT_RERANKER_LOCAL_FORCE_CPU = False  # Force CPU mode for local reranker (avoids MPS/XPC issues on macOS)
 DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT = 4  # Limit concurrent CPU-bound reranking to prevent thrashing
 DEFAULT_RERANKER_TEI_BATCH_SIZE = 128
 DEFAULT_RERANKER_TEI_MAX_CONCURRENT = 8
@@ -203,19 +169,22 @@ 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
+# Mental models defaults
+DEFAULT_ENABLE_MENTAL_MODELS = False  # Mental models disabled by default (experimental)
+DEFAULT_CONSOLIDATION_SIMILARITY_THRESHOLD = 0.75  # Minimum similarity to consider a learning related
 DEFAULT_CONSOLIDATION_BATCH_SIZE = 50  # Memories to load per batch (internal memory optimization)
-DEFAULT_CONSOLIDATION_MAX_TOKENS = 1024  # Max tokens for recall when finding related observations
 
 # Database migrations
 DEFAULT_RUN_MIGRATIONS_ON_STARTUP = True
@@ -309,7 +278,6 @@ class HindsightConfig:
 
     # Database
     database_url: str
-    database_schema: str
 
     # LLM (default, used as fallback for per-operation config)
     llm_provider: str
@@ -317,51 +285,27 @@ class HindsightConfig:
     llm_model: str
     llm_base_url: str | None
     llm_max_concurrent: int
-    llm_max_retries: int
-    llm_initial_backoff: float
-    llm_max_backoff: float
     llm_timeout: float
 
-    # Vertex AI configuration
-    llm_vertexai_project_id: str | None
-    llm_vertexai_region: str
-    llm_vertexai_service_account_key: str | None
-
     # Per-operation LLM configuration (None = use default LLM config)
     retain_llm_provider: str | None
     retain_llm_api_key: str | None
     retain_llm_model: str | None
     retain_llm_base_url: str | None
-    retain_llm_max_concurrent: int | None
-    retain_llm_max_retries: int | None
-    retain_llm_initial_backoff: float | None
-    retain_llm_max_backoff: float | None
-    retain_llm_timeout: float | None
 
     reflect_llm_provider: str | None
     reflect_llm_api_key: str | None
     reflect_llm_model: str | None
     reflect_llm_base_url: str | None
-    reflect_llm_max_concurrent: int | None
-    reflect_llm_max_retries: int | None
-    reflect_llm_initial_backoff: float | None
-    reflect_llm_max_backoff: float | None
-    reflect_llm_timeout: float | None
 
     consolidation_llm_provider: str | None
     consolidation_llm_api_key: str | None
     consolidation_llm_model: str | None
     consolidation_llm_base_url: str | None
-    consolidation_llm_max_concurrent: int | None
-    consolidation_llm_max_retries: int | None
-    consolidation_llm_initial_backoff: float | None
-    consolidation_llm_max_backoff: float | None
-    consolidation_llm_timeout: float | None
 
     # Embeddings
     embeddings_provider: str
     embeddings_local_model: str
-    embeddings_local_force_cpu: bool
     embeddings_tei_url: str | None
     embeddings_openai_base_url: str | None
     embeddings_cohere_base_url: str | None
@@ -369,8 +313,6 @@ class HindsightConfig:
     # Reranker
     reranker_provider: str
     reranker_local_model: str
-    reranker_local_force_cpu: bool
-    reranker_local_max_concurrent: int
     reranker_tei_url: str | None
     reranker_tei_batch_size: int
     reranker_tei_max_concurrent: int
@@ -391,18 +333,21 @@ 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
+    # Mental models settings
+    enable_mental_models: bool
+    consolidation_similarity_threshold: float
     consolidation_batch_size: int
-    consolidation_max_tokens: int
 
     # Optimization flags
     skip_llm_verification: bool
@@ -434,98 +379,35 @@ class HindsightConfig:
         return cls(
             # Database
             database_url=os.getenv(ENV_DATABASE_URL, DEFAULT_DATABASE_URL),
-            database_schema=os.getenv(ENV_DATABASE_SCHEMA, DEFAULT_DATABASE_SCHEMA),
             # LLM
             llm_provider=os.getenv(ENV_LLM_PROVIDER, DEFAULT_LLM_PROVIDER),
             llm_api_key=os.getenv(ENV_LLM_API_KEY),
             llm_model=os.getenv(ENV_LLM_MODEL, DEFAULT_LLM_MODEL),
             llm_base_url=os.getenv(ENV_LLM_BASE_URL) or None,
             llm_max_concurrent=int(os.getenv(ENV_LLM_MAX_CONCURRENT, str(DEFAULT_LLM_MAX_CONCURRENT))),
-            llm_max_retries=int(os.getenv(ENV_LLM_MAX_RETRIES, str(DEFAULT_LLM_MAX_RETRIES))),
-            llm_initial_backoff=float(os.getenv(ENV_LLM_INITIAL_BACKOFF, str(DEFAULT_LLM_INITIAL_BACKOFF))),
-            llm_max_backoff=float(os.getenv(ENV_LLM_MAX_BACKOFF, str(DEFAULT_LLM_MAX_BACKOFF))),
             llm_timeout=float(os.getenv(ENV_LLM_TIMEOUT, str(DEFAULT_LLM_TIMEOUT))),
-            # Vertex AI
-            llm_vertexai_project_id=os.getenv(ENV_LLM_VERTEXAI_PROJECT_ID) or DEFAULT_LLM_VERTEXAI_PROJECT_ID,
-            llm_vertexai_region=os.getenv(ENV_LLM_VERTEXAI_REGION, DEFAULT_LLM_VERTEXAI_REGION),
-            llm_vertexai_service_account_key=os.getenv(ENV_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY)
-            or DEFAULT_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY,
             # Per-operation LLM config (None = use default)
             retain_llm_provider=os.getenv(ENV_RETAIN_LLM_PROVIDER) or None,
             retain_llm_api_key=os.getenv(ENV_RETAIN_LLM_API_KEY) or None,
             retain_llm_model=os.getenv(ENV_RETAIN_LLM_MODEL) or None,
             retain_llm_base_url=os.getenv(ENV_RETAIN_LLM_BASE_URL) or None,
-            retain_llm_max_concurrent=int(os.getenv(ENV_RETAIN_LLM_MAX_CONCURRENT))
-            if os.getenv(ENV_RETAIN_LLM_MAX_CONCURRENT)
-            else None,
-            retain_llm_max_retries=int(os.getenv(ENV_RETAIN_LLM_MAX_RETRIES))
-            if os.getenv(ENV_RETAIN_LLM_MAX_RETRIES)
-            else None,
-            retain_llm_initial_backoff=float(os.getenv(ENV_RETAIN_LLM_INITIAL_BACKOFF))
-            if os.getenv(ENV_RETAIN_LLM_INITIAL_BACKOFF)
-            else None,
-            retain_llm_max_backoff=float(os.getenv(ENV_RETAIN_LLM_MAX_BACKOFF))
-            if os.getenv(ENV_RETAIN_LLM_MAX_BACKOFF)
-            else None,
-            retain_llm_timeout=float(os.getenv(ENV_RETAIN_LLM_TIMEOUT)) if os.getenv(ENV_RETAIN_LLM_TIMEOUT) else None,
             reflect_llm_provider=os.getenv(ENV_REFLECT_LLM_PROVIDER) or None,
             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,
-            reflect_llm_max_concurrent=int(os.getenv(ENV_REFLECT_LLM_MAX_CONCURRENT))
-            if os.getenv(ENV_REFLECT_LLM_MAX_CONCURRENT)
-            else None,
-            reflect_llm_max_retries=int(os.getenv(ENV_REFLECT_LLM_MAX_RETRIES))
-            if os.getenv(ENV_REFLECT_LLM_MAX_RETRIES)
-            else None,
-            reflect_llm_initial_backoff=float(os.getenv(ENV_REFLECT_LLM_INITIAL_BACKOFF))
-            if os.getenv(ENV_REFLECT_LLM_INITIAL_BACKOFF)
-            else None,
-            reflect_llm_max_backoff=float(os.getenv(ENV_REFLECT_LLM_MAX_BACKOFF))
-            if os.getenv(ENV_REFLECT_LLM_MAX_BACKOFF)
-            else None,
-            reflect_llm_timeout=float(os.getenv(ENV_REFLECT_LLM_TIMEOUT))
-            if os.getenv(ENV_REFLECT_LLM_TIMEOUT)
-            else 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,
-            consolidation_llm_max_concurrent=int(os.getenv(ENV_CONSOLIDATION_LLM_MAX_CONCURRENT))
-            if os.getenv(ENV_CONSOLIDATION_LLM_MAX_CONCURRENT)
-            else None,
-            consolidation_llm_max_retries=int(os.getenv(ENV_CONSOLIDATION_LLM_MAX_RETRIES))
-            if os.getenv(ENV_CONSOLIDATION_LLM_MAX_RETRIES)
-            else None,
-            consolidation_llm_initial_backoff=float(os.getenv(ENV_CONSOLIDATION_LLM_INITIAL_BACKOFF))
-            if os.getenv(ENV_CONSOLIDATION_LLM_INITIAL_BACKOFF)
-            else None,
-            consolidation_llm_max_backoff=float(os.getenv(ENV_CONSOLIDATION_LLM_MAX_BACKOFF))
-            if os.getenv(ENV_CONSOLIDATION_LLM_MAX_BACKOFF)
-            else None,
-            consolidation_llm_timeout=float(os.getenv(ENV_CONSOLIDATION_LLM_TIMEOUT))
-            if os.getenv(ENV_CONSOLIDATION_LLM_TIMEOUT)
-            else 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),
-            embeddings_local_force_cpu=os.getenv(
-                ENV_EMBEDDINGS_LOCAL_FORCE_CPU, str(DEFAULT_EMBEDDINGS_LOCAL_FORCE_CPU)
-            ).lower()
-            in ("true", "1"),
             embeddings_tei_url=os.getenv(ENV_EMBEDDINGS_TEI_URL),
             embeddings_openai_base_url=os.getenv(ENV_EMBEDDINGS_OPENAI_BASE_URL) or None,
             embeddings_cohere_base_url=os.getenv(ENV_EMBEDDINGS_COHERE_BASE_URL) or None,
             # Reranker
             reranker_provider=os.getenv(ENV_RERANKER_PROVIDER, DEFAULT_RERANKER_PROVIDER),
             reranker_local_model=os.getenv(ENV_RERANKER_LOCAL_MODEL, DEFAULT_RERANKER_LOCAL_MODEL),
-            reranker_local_force_cpu=os.getenv(
-                ENV_RERANKER_LOCAL_FORCE_CPU, str(DEFAULT_RERANKER_LOCAL_FORCE_CPU)
-            ).lower()
-            in ("true", "1"),
-            reranker_local_max_concurrent=int(
-                os.getenv(ENV_RERANKER_LOCAL_MAX_CONCURRENT, str(DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT))
-            ),
             reranker_tei_url=os.getenv(ENV_RERANKER_TEI_URL),
             reranker_tei_batch_size=int(os.getenv(ENV_RERANKER_TEI_BATCH_SIZE, str(DEFAULT_RERANKER_TEI_BATCH_SIZE))),
             reranker_tei_max_concurrent=int(
@@ -552,6 +434,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))
@@ -564,19 +451,19 @@ 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",
+            # Mental models settings
+            enable_mental_models=os.getenv(ENV_ENABLE_MENTAL_MODELS, str(DEFAULT_ENABLE_MENTAL_MODELS)).lower()
+            == "true",
+            consolidation_similarity_threshold=float(
+                os.getenv(ENV_CONSOLIDATION_SIMILARITY_THRESHOLD, str(DEFAULT_CONSOLIDATION_SIMILARITY_THRESHOLD))
+            ),
             consolidation_batch_size=int(
                 os.getenv(ENV_CONSOLIDATION_BATCH_SIZE, str(DEFAULT_CONSOLIDATION_BATCH_SIZE))
             ),
-            consolidation_max_tokens=int(
-                os.getenv(ENV_CONSOLIDATION_MAX_TOKENS, str(DEFAULT_CONSOLIDATION_MAX_TOKENS))
-            ),
             # Database migrations
             run_migrations_on_startup=os.getenv(ENV_RUN_MIGRATIONS_ON_STARTUP, "true").lower() == "true",
             # Database connection pool
@@ -648,7 +535,7 @@ class HindsightConfig:
 
     def log_config(self) -> None:
         """Log the current configuration (without sensitive values)."""
-        logger.info(f"Database: {self.database_url} (schema: {self.database_schema})")
+        logger.info(f"Database: {self.database_url}")
         logger.info(f"LLM: provider={self.llm_provider}, model={self.llm_model}")
         if self.retain_llm_provider or self.retain_llm_model:
             retain_provider = self.retain_llm_provider or self.llm_provider

hindsight-api/hindsight_api/daemon.py

@@ -52,10 +52,7 @@ class IdleTimeoutMiddleware:
                 logger.info(f"Idle timeout reached ({self.idle_timeout}s), shutting down daemon")
                 # Give a moment for any in-flight requests
                 await asyncio.sleep(1)
-                # Send SIGTERM to ourselves to trigger graceful shutdown
-                import signal
-
-                os.kill(os.getpid(), signal.SIGTERM)
+                os._exit(0)
 
 
 class DaemonLock:

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

@@ -1,13 +1,13 @@
-"""Consolidation engine for automatic observation creation from memories.
+"""Consolidation engine for automatic mental model 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
+- Creates new mental models from novel facts
+- Updates existing mental models when new evidence supports/contradicts/refines them
 
-Observations are stored in memory_units with fact_type='observation' and include:
+Mental models are stored in memory_units with fact_type='mental_model' and include:
 - proof_count: Number of supporting memories
-- source_memory_ids: Array of memory UUIDs that contribute to this observation
+- source_memory_ids: Array of memory UUIDs that contribute to this mental model
 - history: JSONB tracking changes over time
 """
 
@@ -89,7 +89,7 @@ async def run_consolidation_job(
     max_memories_per_batch = config.consolidation_batch_size
 
     # Check if consolidation is enabled
-    if not config.enable_observations:
+    if not config.enable_mental_models:
         logger.debug(f"Consolidation disabled for bank {bank_id}")
         return {"status": "disabled", "bank_id": bank_id}
 
@@ -136,28 +136,24 @@ async def run_consolidation_job(
     # Process each memory with individual commits for crash recovery
     stats = {
         "memories_processed": 0,
-        "observations_created": 0,
-        "observations_updated": 0,
-        "observations_merged": 0,
+        "mental_models_created": 0,
+        "mental_models_updated": 0,
+        "mental_models_merged": 0,
         "actions_executed": 0,
         "skipped": 0,
     }
 
     batch_num = 0
-    last_progress_timings = {}  # Track timings at last progress log
     while True:
         batch_num += 1
         batch_start = time.time()
 
-        # Snapshot timings at batch start for per-batch calculation
-        batch_start_timings = perf.timings.copy()
-
         # 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
+                SELECT id, text, fact_type, occurred_start, event_date, tags, mentioned_at
                 FROM {fq_table("memory_units")}
                 WHERE bank_id = $1
                   AND consolidated_at IS NULL
@@ -205,67 +201,42 @@ async def run_consolidation_job(
 
             action = result.get("action")
             if action == "created":
-                stats["observations_created"] += 1
+                stats["mental_models_created"] += 1
                 stats["actions_executed"] += 1
             elif action == "updated":
-                stats["observations_updated"] += 1
+                stats["mental_models_updated"] += 1
                 stats["actions_executed"] += 1
             elif action == "merged":
-                stats["observations_merged"] += 1
+                stats["mental_models_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["mental_models_created"] += result.get("created", 0)
+                stats["mental_models_updated"] += result.get("updated", 0)
+                stats["mental_models_merged"] += result.get("merged", 0)
                 stats["actions_executed"] += result.get("total_actions", 0)
             elif action == "skipped":
                 stats["skipped"] += 1
 
-            # Log progress periodically with timing breakdown
+            # Log progress periodically
             if stats["memories_processed"] % 10 == 0:
-                # Calculate timing deltas since last progress log
-                timing_parts = []
-                for key in ["recall", "llm", "embedding", "db_write"]:
-                    if key in perf.timings:
-                        delta = perf.timings[key] - last_progress_timings.get(key, 0)
-                        timing_parts.append(f"{key}={delta:.2f}s")
-
-                timing_str = f" | {', '.join(timing_parts)}" if timing_parts else ""
                 logger.info(
                     f"[CONSOLIDATION] bank={bank_id} progress: "
-                    f"{stats['memories_processed']}/{total_count} memories processed{timing_str}"
+                    f"{stats['memories_processed']}/{total_count} memories processed"
                 )
 
-                # Update last progress snapshot
-                last_progress_timings = perf.timings.copy()
-
         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)"
         )
 
-        # Log timing breakdown after each batch (delta from batch start)
-        timing_parts = []
-        for key in ["recall", "llm", "embedding", "db_write"]:
-            if key in perf.timings:
-                delta = perf.timings[key] - batch_start_timings.get(key, 0)
-                timing_parts.append(f"{key}={delta:.3f}s")
-
-        if timing_parts:
-            avg_per_memory = batch_time / len(memories) if memories else 0
-            logger.info(
-                f"[CONSOLIDATION] bank={bank_id} batch {batch_num}/{len(memories)} memories: "
-                f"{', '.join(timing_parts)} | avg={avg_per_memory:.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['mental_models_created']} created, "
+        f"{stats['mental_models_updated']} updated, "
+        f"{stats['mental_models_merged']} merged, "
         f"{stats['skipped']} skipped)"
     )
 
@@ -283,79 +254,11 @@ async def run_consolidation_job(
     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",
@@ -369,13 +272,13 @@ async def _process_memory(
     Process a single memory for consolidation using a SINGLE LLM call.
 
     This function:
-    1. Finds related observations (can be empty)
+    1. Finds related mental models (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
+    - No related models: returns create action(s) with extracted durable knowledge
+    - Related models exist: returns update/create actions based on tag routing
     - Purely ephemeral fact: returns empty array (skip)
 
     Returns:
@@ -385,9 +288,9 @@ async def _process_memory(
     memory_id = memory["id"]
     fact_tags = memory.get("tags") or []
 
-    # Find related observations using the full recall system (NO tag filtering)
+    # Find related mental models using the full recall system (NO tag filtering)
     t0 = time.time()
-    related_observations = await _find_related_observations(
+    related_mental_models = await _find_related_mental_models(
         conn=conn,
         memory_engine=memory_engine,
         bank_id=bank_id,
@@ -397,13 +300,13 @@ async def _process_memory(
     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
+    # Single LLM call handles ALL cases (with or without existing models)
     t0 = time.time()
     actions = await _consolidate_with_llm(
         memory_engine=memory_engine,
         fact_text=fact_text,
-        observations=related_observations,  # Can be empty list
+        fact_tags=fact_tags,
+        mental_models=related_mental_models,  # Can be empty list
         mission=mission,
     )
     if perf:
@@ -424,10 +327,7 @@ async def _process_memory(
                 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"),
+                mental_models=related_mental_models,
                 source_mentioned_at=memory.get("mentioned_at"),
                 perf=perf,
             )
@@ -439,10 +339,8 @@ async def _process_memory(
                 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,
             )
@@ -475,26 +373,15 @@ async def _execute_update_action(
     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,
+    mental_models: list[dict[str, Any]],
     source_mentioned_at: datetime | None = None,
     perf: ConsolidationPerfLog | None = None,
 ) -> dict[str, Any]:
     """
-    Execute an update action on an existing observation.
+    Execute an update action on an existing mental model.
 
-    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.
+    Updates the mental model text, adds to history, increments proof_count,
+    and updates mentioned_at if the new source memory has a more recent date.
     """
     learning_id = action.get("learning_id")
     new_text = action.get("text")
@@ -503,8 +390,8 @@ async def _execute_update_action(
     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)
+    # Find the mental model
+    model = next((m for m in mental_models if str(m["id"]) == learning_id), None)
     if not model:
         return {"action": "skipped", "reason": "learning_not_found"}
 
@@ -523,17 +410,6 @@ async def _execute_update_action(
     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])
@@ -541,11 +417,8 @@ async def _execute_update_action(
     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)
+    # Update the mental model
+    # Update mentioned_at if source memory has a more recent date
     t0 = time.time()
     await conn.execute(
         f"""
@@ -555,11 +428,8 @@ async def _execute_update_action(
             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))
+            mentioned_at = GREATEST(mentioned_at, COALESCE($7, mentioned_at))
         WHERE id = $6
         """,
         new_text,
@@ -568,20 +438,17 @@ async def _execute_update_action(
         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
+    # Create links from memory to mental model
     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}")
+    logger.debug(f"Updated mental model {learning_id} with memory {memory_id}")
 
-    return {"action": "updated", "observation_id": learning_id}
+    return {"action": "updated", "mental_model_id": learning_id}
 
 
 async def _execute_create_action(
@@ -590,48 +457,38 @@ async def _execute_create_action(
     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.
+    Execute a create action for a new mental model.
 
-    Creates a new observation with the specified text.
+    Creates a new mental model with the specified text and tags.
     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 []
+    tags = action.get("tags", [])
 
     if not text:
         return {"action": "skipped", "reason": "missing_text"}
 
     # Use text directly from classify - skip the redundant LLM call
-    result = await _create_observation_directly(
+    result = await _create_mental_model_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
+        mental_model_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})")
+    logger.debug(f"Created mental model {result.get('mental_model_id')} from memory {memory_id} (tags: {tags})")
 
     return result
 
@@ -639,28 +496,98 @@ async def _execute_create_action(
 async def _create_memory_links(
     conn: "Connection",
     memory_id: uuid.UUID,
-    observation_id: uuid.UUID,
+    mental_model_id: uuid.UUID,
 ) -> None:
     """
-    Placeholder for observation link creation.
+    Create links between a source memory and its mental model.
 
-    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:
+    1. Creates bidirectional semantic links between memory and mental model
+    2. Copies existing memory_links from the source memory to the mental model
+    3. Copies entity links from the source memory to the mental model
 
-    This avoids data duplication and ensures observations are always
-    connected via their source facts' relationships.
+    This enables graph traversal to find related memories via their mental models.
 
-    The memory_id and observation_id parameters are kept for interface
-    compatibility but no links are created.
+    Note: Uses EXISTS checks to handle the case where source memory was deleted
+    by a concurrent operation between fetching and link creation.
     """
-    # No links are created - observations rely on source_memory_ids for traversal
-    pass
+    mu_table = fq_table("memory_units")
+    ml_table = fq_table("memory_links")
+    ue_table = fq_table("unit_entities")
+
+    # 1. Bidirectional link between memory and mental model
+    # Only insert if both units exist (handles concurrent deletion)
+    await conn.execute(
+        f"""
+        INSERT INTO {ml_table} (from_unit_id, to_unit_id, link_type, weight)
+        SELECT $1, $2, 'semantic', 1.0
+        WHERE EXISTS (SELECT 1 FROM {mu_table} WHERE id = $1)
+          AND EXISTS (SELECT 1 FROM {mu_table} WHERE id = $2)
+        ON CONFLICT DO NOTHING
+        """,
+        memory_id,
+        mental_model_id,
+    )
+    await conn.execute(
+        f"""
+        INSERT INTO {ml_table} (from_unit_id, to_unit_id, link_type, weight)
+        SELECT $1, $2, 'semantic', 1.0
+        WHERE EXISTS (SELECT 1 FROM {mu_table} WHERE id = $1)
+          AND EXISTS (SELECT 1 FROM {mu_table} WHERE id = $2)
+        ON CONFLICT DO NOTHING
+        """,
+        mental_model_id,
+        memory_id,
+    )
+
+    # 2. Copy outgoing memory_links from source memory to mental model
+    # If source memory links to X, mental model should also link to X
+    await conn.execute(
+        f"""
+        INSERT INTO {ml_table} (from_unit_id, to_unit_id, link_type, entity_id, weight)
+        SELECT $1, ml.to_unit_id, ml.link_type, ml.entity_id, ml.weight
+        FROM {ml_table} ml
+        WHERE ml.from_unit_id = $2 AND ml.to_unit_id != $1
+          AND EXISTS (SELECT 1 FROM {mu_table} WHERE id = $1)
+          AND EXISTS (SELECT 1 FROM {mu_table} WHERE id = ml.to_unit_id)
+        ON CONFLICT DO NOTHING
+        """,
+        mental_model_id,
+        memory_id,
+    )
+
+    # 3. Copy incoming memory_links from source memory to mental model
+    # If X links to source memory, X should also link to mental model
+    await conn.execute(
+        f"""
+        INSERT INTO {ml_table} (from_unit_id, to_unit_id, link_type, entity_id, weight)
+        SELECT ml.from_unit_id, $1, ml.link_type, ml.entity_id, ml.weight
+        FROM {ml_table} ml
+        WHERE ml.to_unit_id = $2 AND ml.from_unit_id != $1
+          AND EXISTS (SELECT 1 FROM {mu_table} WHERE id = $1)
+          AND EXISTS (SELECT 1 FROM {mu_table} WHERE id = ml.from_unit_id)
+        ON CONFLICT DO NOTHING
+        """,
+        mental_model_id,
+        memory_id,
+    )
+
+    # 4. Copy entity links from source memory to mental model
+    await conn.execute(
+        f"""
+        INSERT INTO {ue_table} (unit_id, entity_id)
+        SELECT $1, ue.entity_id
+        FROM {ue_table} ue
+        WHERE ue.unit_id = $2
+          AND EXISTS (SELECT 1 FROM {mu_table} WHERE id = $1)
+        ON CONFLICT DO NOTHING
+        """,
+        mental_model_id,
+        memory_id,
+    )
 
 
-async def _find_related_observations(
+async def _find_related_mental_models(
     conn: "Connection",
     memory_engine: "MemoryEngine",
     bank_id: str,
@@ -668,174 +595,104 @@ async def _find_related_observations(
     request_context: "RequestContext",
 ) -> list[dict[str, Any]]:
     """
-    Find observations related to the given query using optimized recall.
+    Find mental models 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
+    potentially related mental models regardless of scope, so the LLM can
     decide on tag routing (same scope update vs cross-scope create).
 
-    Uses max_tokens to naturally limit observations (no artificial count limit).
-    Includes source memories with dates for LLM context.
+    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, source memories, and dates
+        List of related mental models with their tags for LLM tag routing
     """
-    # Use recall to find related observations with token budget
-    # max_tokens naturally limits how many observations are returned
-    from ...config import get_config
-
-    config = get_config()
+    # Use recall to find related mental models
+    # NO tags parameter - we want ALL mental models regardless of scope
+    # Use low max_tokens since we only need mental models, not memories
     recall_result = await memory_engine.recall_async(
         bank_id=bank_id,
         query=query,
-        max_tokens=config.consolidation_max_tokens,  # Token budget for observations (configurable)
-        fact_type=["observation"],  # Only retrieve observations
+        max_tokens=5000,  # Token budget for mental models
+        fact_type=["mental_model"],  # Only retrieve mental models
         request_context=request_context,
         _quiet=True,  # Suppress logging
-        # NO tags parameter - intentionally get ALL observations
+        # NO tags parameter - intentionally get ALL mental models
     )
 
-    # If no observations returned, return empty list
+    # If no mental models returned, return empty list
+    # When fact_type=["mental_model"], results come back in `results` field
     if not recall_result.results:
         return []
 
-    # Batch fetch all observations in a single query (no artificial limit)
-    observation_ids = [uuid.UUID(obs.id) for obs in recall_result.results]
-
-    rows = await conn.fetch(
-        f"""
-        SELECT id, text, proof_count, history, tags, source_memory_ids, created_at, updated_at,
-               occurred_start, occurred_end, mentioned_at
-        FROM {fq_table("memory_units")}
-        WHERE id = ANY($1) AND bank_id = $2 AND fact_type = 'observation'
-        """,
-        observation_ids,
-        bank_id,
-    )
-
-    # Build results list preserving recall order
-    id_to_row = {row["id"]: row for row in rows}
+    # Trust recall's relevance filtering - fetch full data for each mental model
     results = []
-
-    for obs in recall_result.results:
-        obs_id = uuid.UUID(obs.id)
-        if obs_id not in id_to_row:
-            continue
-
-        row = id_to_row[obs_id]
-        history = row["history"]
-        if isinstance(history, str):
-            history = json.loads(history)
-        elif history is None:
-            history = []
-
-        # Fetch source memories to include their text and dates
-        source_memory_ids = row["source_memory_ids"] or []
-        source_memories = []
-
-        if source_memory_ids:
-            source_rows = await conn.fetch(
-                f"""
-                SELECT text, occurred_start, occurred_end, mentioned_at, event_date
-                FROM {fq_table("memory_units")}
-                WHERE id = ANY($1) AND bank_id = $2
-                ORDER BY created_at ASC
-                LIMIT 5
-                """,
-                source_memory_ids[:5],  # Limit to first 5 source memories for token efficiency
-                bank_id,
-            )
-
-            for src_row in source_rows:
-                source_memories.append(
-                    {
-                        "text": src_row["text"],
-                        "occurred_start": src_row["occurred_start"],
-                        "occurred_end": src_row["occurred_end"],
-                        "mentioned_at": src_row["mentioned_at"],
-                        "event_date": src_row["event_date"],
-                    }
-                )
-
-        results.append(
-            {
-                "id": row["id"],
-                "text": row["text"],
-                "proof_count": row["proof_count"] or 1,
-                "tags": row["tags"] or [],
-                "source_memories": source_memories,
-                "occurred_start": row["occurred_start"],
-                "occurred_end": row["occurred_end"],
-                "mentioned_at": row["mentioned_at"],
-                "created_at": row["created_at"],
-                "updated_at": row["updated_at"],
-            }
+    for mm in recall_result.results:
+        # Fetch full mental model 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 = 'mental_model'
+            """,
+            uuid.UUID(mm.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]],
+    fact_tags: list[str],
+    mental_models: 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
+    - No related mental models: extracts durable knowledge, returns create action
+    - Related models 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": "..."}
+        - {"action": "create", "tags": [...], "text": "...", "reason": "..."}
         - [] if fact is purely ephemeral (no durable knowledge)
     """
-    # Format observations as JSON with source memories and dates
-    if observations:
-        obs_list = []
-        for obs in observations:
-            obs_data = {
-                "id": str(obs["id"]),
-                "text": obs["text"],
-                "proof_count": obs["proof_count"],
-                "tags": obs["tags"],
-                "created_at": obs["created_at"].isoformat() if obs.get("created_at") else None,
-                "updated_at": obs["updated_at"].isoformat() if obs.get("updated_at") else None,
-            }
-
-            # Include temporal info if available
-            if obs.get("occurred_start"):
-                obs_data["occurred_start"] = obs["occurred_start"].isoformat()
-            if obs.get("occurred_end"):
-                obs_data["occurred_end"] = obs["occurred_end"].isoformat()
-            if obs.get("mentioned_at"):
-                obs_data["mentioned_at"] = obs["mentioned_at"].isoformat()
-
-            # Include source memories (up to 3 for brevity)
-            if obs.get("source_memories"):
-                obs_data["source_memories"] = [
-                    {
-                        "text": sm["text"],
-                        "event_date": sm["event_date"].isoformat() if sm.get("event_date") else None,
-                        "occurred_start": sm["occurred_start"].isoformat() if sm.get("occurred_start") else None,
-                    }
-                    for sm in obs["source_memories"][:3]  # Limit to 3 for token efficiency
-                ]
-
-            obs_list.append(obs_data)
-
-        observations_text = json.dumps(obs_list, indent=2)
+    # Format mental models WITH their tags (or "None" if empty)
+    if mental_models:
+        mental_models_text = "\n".join(
+            f'- ID: {mm["id"]}, Tags: {json.dumps(mm["tags"])}, Text: "{mm["text"]}" (proof_count: {mm["proof_count"]})'
+            for mm in mental_models
+        )
     else:
-        observations_text = "[]"
+        mental_models_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 = ""
@@ -849,7 +706,8 @@ 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,
+        fact_tags=json.dumps(fact_tags),
+        mental_models_text=mental_models_text,
     )
 
     messages = [
@@ -888,68 +746,65 @@ Focus on DURABLE knowledge that serves this mission, not ephemeral state.
         return []
 
 
-async def _create_observation_directly(
+async def _create_mental_model_directly(
     conn: "Connection",
     memory_engine: "MemoryEngine",
     bank_id: str,
     source_memory_id: uuid.UUID,
-    observation_text: str,
+    mental_model_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).
+    Create a mental model 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)
+    # Generate embedding for the mental model (convert to string for pgvector)
     t0 = time.time()
-    embeddings = await embedding_utils.generate_embeddings_batch(memory_engine.embeddings, [observation_text])
+    embeddings = await embedding_utils.generate_embeddings_batch(memory_engine.embeddings, [mental_model_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
+    # Create the mental model 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 []
+    mm_event_date = event_date or now
+    mm_occurred_start = occurred_start or now
+    mm_mentioned_at = mentioned_at or now
+    mm_tags = tags or []
 
     t0 = time.time()
-    observation_id = uuid.uuid4()
+    mental_model_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
+            tags, event_date, occurred_start, mentioned_at
         )
-        VALUES ($1, $2, $3, 'observation', $4::vector, 1, $5, '[]'::jsonb, $6, $7, $8, $9, $10)
+        VALUES ($1, $2, $3, 'mental_model', $4::vector, 1, $5, '[]'::jsonb, $6, $7, $8, $9)
         RETURNING id
         """,
-        observation_id,
+        mental_model_id,
         bank_id,
-        observation_text,
+        mental_model_text,
         embedding_str,
         [source_memory_id],
-        obs_tags,
-        obs_event_date,
-        obs_occurred_start,
-        obs_occurred_end,
-        obs_mentioned_at,
+        mm_tags,
+        mm_event_date,
+        mm_occurred_start,
+        mm_mentioned_at,
     )
 
-    # Create links between memory and observation (includes entity links, memory_links)
-    await _create_memory_links(conn, source_memory_id, observation_id)
+    # Create links between memory and mental model (includes entity links, memory_links)
+    await _create_memory_links(conn, source_memory_id, mental_model_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})")
+    logger.debug(f"Created mental model {mental_model_id} from memory {source_memory_id} (tags: {mm_tags})")
 
-    return {"action": "created", "observation_id": str(row["id"]), "tags": obs_tags}
+    return {"action": "created", "mental_model_id": str(row["id"]), "tags": mm_tags}

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

@@ -1,6 +1,6 @@
 """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.
+CONSOLIDATION_SYSTEM_PROMPT = """You are a memory consolidation system. Your job is to convert facts into durable knowledge (mental models) and merge with existing knowledge when appropriate.
 
 You must output ONLY valid JSON with no markdown formatting, no code blocks, and no additional text.
 
@@ -30,48 +30,62 @@ 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):
+## MERGE RULES (when comparing to existing mental models):
 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
 
+## TAG ROUTING RULES:
+Tags define visibility scopes. The fact and each mental model have tags (can be empty = global).
+
+| Fact Tags | Model Tags | Action |
+|-----------|------------|--------|
+| [alice] | [alice] | UPDATE the model (same scope) |
+| [alice] | [] | UPDATE the model (global absorbs all scopes) |
+| [alice] | [bob] | CREATE new untagged model (cross-scope insight) |
+| [] | [alice] | UPDATE the model (untagged facts can update any scope) |
+| [] | [] | UPDATE the model (global to global) |
+
+When NO existing model matches the fact's topic: CREATE new model with fact's tags.
+
+## MULTIPLE ACTIONS:
+One fact can trigger MULTIPLE actions. For example:
+- Update a scoped model [alice] about pizza preferences
+- AND update a global model [] about pizza in general
+
+Output an ARRAY of actions (can be empty, one, or many).
+
 ## 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"""
+- Keep mental models focused on ONE specific topic per person
+- Cross-scope insights (alice's fact about bob's topic) become UNTAGGED (global)
+- The "text" field MUST contain durable knowledge, not ephemeral state"""
 
 CONSOLIDATION_USER_PROMPT = """Analyze this new fact and consolidate into knowledge.
 {mission_section}
 NEW FACT: {fact_text}
+FACT TAGS: {fact_tags}
 
-EXISTING OBSERVATIONS (JSON array with source memories and dates):
-{observations_text}
-
-Each observation includes:
-- id: unique identifier for updating
-- text: the observation content
-- proof_count: number of supporting memories
-- tags: visibility scope (handled automatically)
-- created_at/updated_at: when observation was created/modified
-- occurred_start/occurred_end: temporal range of source facts
-- source_memories: array of supporting facts with their text and dates
+EXISTING MENTAL MODELS:
+{mental_models_text}
 
 Instructions:
-1. Extract DURABLE KNOWLEDGE from the new fact (not ephemeral state)
-2. Review source_memories in existing observations to understand evidence
-3. Check dates to detect contradictions or updates
-4. Compare with observations:
-   - Same topic → UPDATE with learning_id
-   - New topic → CREATE new observation
-   - Purely ephemeral → return []
+1. First, extract the DURABLE KNOWLEDGE from the fact (not ephemeral state like "user is at X")
+2. Then compare with existing mental models:
+   - If a model covers the same topic: UPDATE it with the new knowledge
+   - If no model covers the topic: CREATE a new one
+   - If fact is about different scope: apply tag routing rules
 
-Output JSON array of actions:
+Output JSON array of actions (ALWAYS an array, even for single action):
 [
-  {{"action": "update", "learning_id": "uuid-from-observations", "text": "updated knowledge", "reason": "..."}},
-  {{"action": "create", "text": "new durable knowledge", "reason": "..."}}
+  {{"action": "update", "learning_id": "uuid", "text": "updated durable knowledge", "reason": "..."}},
+  {{"action": "create", "tags": ["tag"], "text": "new durable knowledge", "reason": "..."}}
 ]
 
-Return [] if fact contains no durable knowledge."""
+If NO consolidation is needed (fact is purely ephemeral with no durable knowledge):
+[]
+
+If no models exist and fact contains durable knowledge:
+[{{"action": "create", "tags": {fact_tags}, "text": "durable knowledge text", "reason": "new topic"}}]"""

hindsight-api/hindsight_api/engine/cross_encoder.py

@@ -20,7 +20,6 @@ from ..config import (
     DEFAULT_RERANKER_FLASHRANK_CACHE_DIR,
     DEFAULT_RERANKER_FLASHRANK_MODEL,
     DEFAULT_RERANKER_LITELLM_MODEL,
-    DEFAULT_RERANKER_LOCAL_FORCE_CPU,
     DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT,
     DEFAULT_RERANKER_LOCAL_MODEL,
     DEFAULT_RERANKER_PROVIDER,
@@ -34,7 +33,6 @@ from ..config import (
     ENV_RERANKER_FLASHRANK_CACHE_DIR,
     ENV_RERANKER_FLASHRANK_MODEL,
     ENV_RERANKER_LITELLM_MODEL,
-    ENV_RERANKER_LOCAL_FORCE_CPU,
     ENV_RERANKER_LOCAL_MAX_CONCURRENT,
     ENV_RERANKER_LOCAL_MODEL,
     ENV_RERANKER_PROVIDER,
@@ -101,7 +99,7 @@ class LocalSTCrossEncoder(CrossEncoderModel):
     _executor: ThreadPoolExecutor | None = None
     _max_concurrent: int = 4  # Limit concurrent CPU-bound reranking calls
 
-    def __init__(self, model_name: str | None = None, max_concurrent: int = 4, force_cpu: bool = False):
+    def __init__(self, model_name: str | None = None, max_concurrent: int = 4):
         """
         Initialize local SentenceTransformers cross-encoder.
 
@@ -110,11 +108,8 @@ class LocalSTCrossEncoder(CrossEncoderModel):
                        Default: cross-encoder/ms-marco-MiniLM-L-6-v2
             max_concurrent: Maximum concurrent reranking calls (default: 2).
                            Higher values may cause CPU thrashing under load.
-            force_cpu: Force CPU mode (avoids MPS/XPC issues on macOS in daemon mode).
-                      Default: False
         """
         self.model_name = model_name or DEFAULT_RERANKER_LOCAL_MODEL
-        self.force_cpu = force_cpu
         self._model = None
         LocalSTCrossEncoder._max_concurrent = max_concurrent
 
@@ -144,23 +139,13 @@ class LocalSTCrossEncoder(CrossEncoderModel):
         # after loading, which conflicts with accelerate's device_map handling.
         import torch
 
-        # Force CPU mode if configured (used in daemon mode to avoid MPS/XPC issues on macOS)
-        if self.force_cpu:
-            device = "cpu"
-            logger.info("Reranker: forcing CPU mode (HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU=1)")
+        # 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
         else:
-            # Check for GPU (CUDA) or Apple Silicon (MPS)
-            # Wrap in try-except to gracefully handle any device detection issues
-            # (e.g., in CI environments or when PyTorch is built without GPU support)
-            device = "cpu"  # Default to CPU
-            try:
-                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
-            except Exception as e:
-                logger.warning(f"Failed to detect GPU/MPS, falling back to CPU: {e}")
+            device = "cpu"
 
         self._model = CrossEncoder(
             self.model_name,
@@ -178,11 +163,6 @@ class LocalSTCrossEncoder(CrossEncoderModel):
         else:
             logger.info("Reranker: local provider initialized (using existing executor)")
 
-    def _predict_sync(self, pairs: list[tuple[str, str]]) -> list[float]:
-        """Synchronous prediction wrapper for thread pool execution."""
-        scores = self._model.predict(pairs, show_progress_bar=False)
-        return scores.tolist() if hasattr(scores, "tolist") else list(scores)
-
     async def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
         """
         Score query-document pairs for relevance.
@@ -200,11 +180,11 @@ class LocalSTCrossEncoder(CrossEncoderModel):
 
         # Use dedicated executor - limited workers naturally limits concurrency
         loop = asyncio.get_event_loop()
-        return await loop.run_in_executor(
+        scores = await loop.run_in_executor(
             LocalSTCrossEncoder._executor,
-            self._predict_sync,
-            pairs,
+            lambda: self._model.predict(pairs, show_progress_bar=False),
         )
+        return scores.tolist() if hasattr(scores, "tolist") else list(scores)
 
 
 class RemoteTEICrossEncoder(CrossEncoderModel):
@@ -614,7 +594,7 @@ class FlashRankCrossEncoder(CrossEncoderModel):
             return
 
         try:
-            from flashrank import Ranker
+            from flashrank import Ranker  # type: ignore[import-untyped]
         except ImportError:
             raise ImportError("flashrank is required for FlashRankCrossEncoder. Install it with: pip install flashrank")
 
@@ -641,7 +621,7 @@ class FlashRankCrossEncoder(CrossEncoderModel):
 
     def _predict_sync(self, pairs: list[tuple[str, str]]) -> list[float]:
         """Synchronous predict - processes each query group."""
-        from flashrank import RerankRequest
+        from flashrank import RerankRequest  # type: ignore[import-untyped]
 
         if not pairs:
             return []
@@ -803,33 +783,29 @@ class LiteLLMCrossEncoder(CrossEncoderModel):
 
 def create_cross_encoder_from_env() -> CrossEncoderModel:
     """
-    Create a CrossEncoderModel instance based on configuration.
+    Create a CrossEncoderModel instance based on environment variables.
 
-    Reads configuration via get_config() to ensure consistency across the codebase.
+    See hindsight_api.config for environment variable names and defaults.
 
     Returns:
         Configured CrossEncoderModel instance
     """
-    from ..config import get_config
-
-    config = get_config()
-    provider = config.reranker_provider.lower()
+    provider = os.environ.get(ENV_RERANKER_PROVIDER, DEFAULT_RERANKER_PROVIDER).lower()
 
     if provider == "tei":
-        url = config.reranker_tei_url
+        url = os.environ.get(ENV_RERANKER_TEI_URL)
         if not url:
             raise ValueError(f"{ENV_RERANKER_TEI_URL} is required when {ENV_RERANKER_PROVIDER} is 'tei'")
-        return RemoteTEICrossEncoder(
-            base_url=url,
-            batch_size=config.reranker_tei_batch_size,
-            max_concurrent=config.reranker_tei_max_concurrent,
-        )
+        batch_size = int(os.environ.get(ENV_RERANKER_TEI_BATCH_SIZE, str(DEFAULT_RERANKER_TEI_BATCH_SIZE)))
+        max_concurrent = int(os.environ.get(ENV_RERANKER_TEI_MAX_CONCURRENT, str(DEFAULT_RERANKER_TEI_MAX_CONCURRENT)))
+        return RemoteTEICrossEncoder(base_url=url, batch_size=batch_size, max_concurrent=max_concurrent)
     elif provider == "local":
-        return LocalSTCrossEncoder(
-            model_name=config.reranker_local_model,
-            max_concurrent=config.reranker_local_max_concurrent,
-            force_cpu=config.reranker_local_force_cpu,
+        model = os.environ.get(ENV_RERANKER_LOCAL_MODEL)
+        model_name = model or DEFAULT_RERANKER_LOCAL_MODEL
+        max_concurrent = int(
+            os.environ.get(ENV_RERANKER_LOCAL_MAX_CONCURRENT, str(DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT))
         )
+        return LocalSTCrossEncoder(model_name=model_name, max_concurrent=max_concurrent)
     elif provider == "cohere":
         api_key = os.environ.get(ENV_COHERE_API_KEY)
         if not api_key:

hindsight-api/hindsight_api/engine/embeddings.py

@@ -18,7 +18,6 @@ import httpx
 from ..config import (
     DEFAULT_EMBEDDINGS_COHERE_MODEL,
     DEFAULT_EMBEDDINGS_LITELLM_MODEL,
-    DEFAULT_EMBEDDINGS_LOCAL_FORCE_CPU,
     DEFAULT_EMBEDDINGS_LOCAL_MODEL,
     DEFAULT_EMBEDDINGS_OPENAI_MODEL,
     DEFAULT_EMBEDDINGS_PROVIDER,
@@ -27,7 +26,6 @@ from ..config import (
     ENV_EMBEDDINGS_COHERE_BASE_URL,
     ENV_EMBEDDINGS_COHERE_MODEL,
     ENV_EMBEDDINGS_LITELLM_MODEL,
-    ENV_EMBEDDINGS_LOCAL_FORCE_CPU,
     ENV_EMBEDDINGS_LOCAL_MODEL,
     ENV_EMBEDDINGS_OPENAI_API_KEY,
     ENV_EMBEDDINGS_OPENAI_BASE_URL,
@@ -94,18 +92,15 @@ class LocalSTEmbeddings(Embeddings):
     The embedding dimension is auto-detected from the model.
     """
 
-    def __init__(self, model_name: str | None = None, force_cpu: bool = False):
+    def __init__(self, model_name: str | None = None):
         """
         Initialize local SentenceTransformers embeddings.
 
         Args:
             model_name: Name of the SentenceTransformer model to use.
                        Default: BAAI/bge-small-en-v1.5
-            force_cpu: Force CPU mode (avoids MPS/XPC issues on macOS in daemon mode).
-                      Default: False
         """
         self.model_name = model_name or DEFAULT_EMBEDDINGS_LOCAL_MODEL
-        self.force_cpu = force_cpu
         self._model = None
         self._dimension: int | None = None
 
@@ -139,23 +134,13 @@ class LocalSTEmbeddings(Embeddings):
         # which can cause issues when accelerate is installed but no GPU is available.
         import torch
 
-        # Force CPU mode if configured (used in daemon mode to avoid MPS/XPC issues on macOS)
-        if self.force_cpu:
-            device = "cpu"
-            logger.info("Embeddings: forcing CPU mode")
+        # 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
         else:
-            # Check for GPU (CUDA) or Apple Silicon (MPS)
-            # Wrap in try-except to gracefully handle any device detection issues
-            # (e.g., in CI environments or when PyTorch is built without GPU support)
-            device = "cpu"  # Default to CPU
-            try:
-                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
-            except Exception as e:
-                logger.warning(f"Failed to detect GPU/MPS, falling back to CPU: {e}")
+            device = "cpu"
 
         self._model = SentenceTransformer(
             self.model_name,
@@ -178,7 +163,6 @@ class LocalSTEmbeddings(Embeddings):
         """
         if self._model is None:
             raise RuntimeError("Embeddings not initialized. Call initialize() first.")
-
         embeddings = self._model.encode(texts, convert_to_numpy=True, show_progress_bar=False)
         return [emb.tolist() for emb in embeddings]
 
@@ -545,7 +529,7 @@ class CohereEmbeddings(Embeddings):
                 model=self.model,
                 input_type=self.input_type,
             )
-            if response.embeddings and isinstance(response.embeddings, list):
+            if response.embeddings:
                 self._dimension = len(response.embeddings[0])
 
         logger.info(f"Embeddings: Cohere provider initialized (model: {self.model}, dim: {self._dimension})")
@@ -702,28 +686,24 @@ class LiteLLMEmbeddings(Embeddings):
 
 def create_embeddings_from_env() -> Embeddings:
     """
-    Create an Embeddings instance based on configuration.
+    Create an Embeddings instance based on environment variables.
 
-    Reads configuration via get_config() to ensure consistency across the codebase.
+    See hindsight_api.config for environment variable names and defaults.
 
     Returns:
         Configured Embeddings instance
     """
-    from ..config import get_config
-
-    config = get_config()
-    provider = config.embeddings_provider.lower()
+    provider = os.environ.get(ENV_EMBEDDINGS_PROVIDER, DEFAULT_EMBEDDINGS_PROVIDER).lower()
 
     if provider == "tei":
-        url = config.embeddings_tei_url
+        url = os.environ.get(ENV_EMBEDDINGS_TEI_URL)
         if not url:
             raise ValueError(f"{ENV_EMBEDDINGS_TEI_URL} is required when {ENV_EMBEDDINGS_PROVIDER} is 'tei'")
         return RemoteTEIEmbeddings(base_url=url)
     elif provider == "local":
-        return LocalSTEmbeddings(
-            model_name=config.embeddings_local_model,
-            force_cpu=config.embeddings_local_force_cpu,
-        )
+        model = os.environ.get(ENV_EMBEDDINGS_LOCAL_MODEL)
+        model_name = model or DEFAULT_EMBEDDINGS_LOCAL_MODEL
+        return LocalSTEmbeddings(model_name=model_name)
     elif provider == "openai":
         # Use dedicated embeddings API key, or fall back to LLM API key
         api_key = os.environ.get(ENV_EMBEDDINGS_OPENAI_API_KEY) or os.environ.get(ENV_LLM_API_KEY)

hindsight-api/hindsight_api/engine/llm_wrapper.py

@@ -16,15 +16,6 @@ from google.genai import errors as genai_errors
 from google.genai import types as genai_types
 from openai import APIConnectionError, APIStatusError, AsyncOpenAI, LengthFinishReasonError
 
-# Vertex AI imports (conditional)
-try:
-    import google.auth
-    from google.oauth2 import service_account
-
-    VERTEXAI_AVAILABLE = True
-except ImportError:
-    VERTEXAI_AVAILABLE = False
-
 from ..config import (
     DEFAULT_LLM_MAX_CONCURRENT,
     DEFAULT_LLM_TIMEOUT,
@@ -97,7 +88,7 @@ class LLMProvider:
         self.groq_service_tier = groq_service_tier or os.getenv(ENV_LLM_GROQ_SERVICE_TIER, "auto")
 
         # Validate provider
-        valid_providers = ["openai", "groq", "ollama", "gemini", "anthropic", "lmstudio", "vertexai", "mock"]
+        valid_providers = ["openai", "groq", "ollama", "gemini", "anthropic", "lmstudio", "mock"]
         if self.provider not in valid_providers:
             raise ValueError(f"Invalid LLM provider: {self.provider}. Must be one of: {', '.join(valid_providers)}")
 
@@ -105,9 +96,6 @@ class LLMProvider:
         self._mock_calls: list[dict] = []
         self._mock_response: Any = None
 
-        # Vertex AI token refresher
-        self._vertexai_refresher: Any = None
-
         # Set default base URLs
         if not self.base_url:
             if self.provider == "groq":
@@ -117,65 +105,8 @@ class LLMProvider:
             elif self.provider == "lmstudio":
                 self.base_url = "http://localhost:1234/v1"
 
-        # Handle Vertex AI provider
-        if self.provider == "vertexai":
-            if not VERTEXAI_AVAILABLE:
-                raise ValueError("Vertex AI requires 'google-auth' package. Install with: pip install google-auth")
-
-            from ..config import get_config
-
-            config = get_config()
-
-            project_id = config.llm_vertexai_project_id
-            if not project_id:
-                raise ValueError(
-                    "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID is required for Vertex AI provider. "
-                    "Set it to your GCP project ID."
-                )
-
-            region = config.llm_vertexai_region or "us-central1"
-            service_account_key = config.llm_vertexai_service_account_key
-
-            # Try ADC first
-            credentials = None
-            auth_method = None
-
-            try:
-                credentials, _ = google.auth.default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
-                auth_method = "ADC"
-                logger.info("Vertex AI: Using Application Default Credentials")
-            except google.auth.exceptions.DefaultCredentialsError:
-                logger.debug("Vertex AI: ADC not available, trying service account")
-
-            # Fall back to service account key file
-            if credentials is None and service_account_key:
-                try:
-                    credentials = service_account.Credentials.from_service_account_file(
-                        service_account_key,
-                        scopes=["https://www.googleapis.com/auth/cloud-platform"],
-                    )
-                    auth_method = "Service Account"
-                    logger.info(f"Vertex AI: Using service account key: {service_account_key}")
-                except Exception as e:
-                    logger.error(f"Vertex AI: Failed to load service account key: {e}")
-
-            if credentials is None:
-                raise ValueError(
-                    "Vertex AI authentication failed. Either:\n"
-                    "  1. Set up ADC: gcloud auth application-default login\n"
-                    "  2. Set HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY to path of service account JSON key"
-                )
-
-            # Initialize token refresher
-            from .vertexai_token_refresher import VertexAITokenRefresher
-
-            self._vertexai_refresher = VertexAITokenRefresher(credentials, project_id, region)
-            self.base_url = self._vertexai_refresher.get_base_url()
-
-            logger.info(f"Vertex AI: project={project_id}, region={region}, auth={auth_method}")
-
-        # Validate API key (not needed for ollama, lmstudio, vertexai, or mock)
-        if self.provider not in ("ollama", "lmstudio", "vertexai", "mock") and not self.api_key:
+        # Validate API key (not needed for ollama, lmstudio, or mock)
+        if self.provider not in ("ollama", "lmstudio", "mock") and not self.api_key:
             raise ValueError(f"API key not found for {self.provider}")
 
         # Get timeout config (set HINDSIGHT_API_LLM_TIMEOUT for local LLMs that need longer timeouts)
@@ -201,31 +132,6 @@ class LLMProvider:
             if self.timeout:
                 anthropic_kwargs["timeout"] = self.timeout
             self._anthropic_client = AsyncAnthropic(**anthropic_kwargs)
-        elif self.provider == "vertexai":
-            # Custom transport for token injection
-            class TokenInjectingTransport(httpx.AsyncHTTPTransport):
-                def __init__(self, refresher, *args, **kwargs):
-                    super().__init__(*args, **kwargs)
-                    self._refresher = refresher
-
-                async def handle_async_request(self, request):
-                    token = self._refresher.get_token()
-                    request.headers["Authorization"] = f"Bearer {token}"
-                    return await super().handle_async_request(request)
-
-            transport = TokenInjectingTransport(self._vertexai_refresher)
-            client_kwargs = {
-                "api_key": "dummy",  # Required by AsyncOpenAI but unused (we inject token via transport)
-                "base_url": self.base_url,
-                "max_retries": 0,
-                "http_client": httpx.AsyncClient(transport=transport),
-            }
-            if self.timeout:
-                client_kwargs["timeout"] = self.timeout
-            self._client = AsyncOpenAI(**client_kwargs)
-
-            # Start background refresh
-            self._vertexai_refresher.start_refresh_task()
         elif self.provider in ("ollama", "lmstudio"):
             # Use dummy key if not provided for local
             api_key = self.api_key or "local"
@@ -436,13 +342,11 @@ class LLMProvider:
                         schema_msg = f"\n\nYou must respond with valid JSON matching this schema:\n{json.dumps(schema, indent=2)}"
 
                         if call_params["messages"] and call_params["messages"][0].get("role") == "system":
-                            first_msg = call_params["messages"][0]
-                            if isinstance(first_msg, dict) and isinstance(first_msg.get("content"), str):
-                                first_msg["content"] += schema_msg
+                            call_params["messages"][0]["content"] += schema_msg
                         elif call_params["messages"]:
-                            first_msg = call_params["messages"][0]
-                            if isinstance(first_msg, dict) and isinstance(first_msg.get("content"), str):
-                                first_msg["content"] = schema_msg + "\n\n" + first_msg["content"]
+                            call_params["messages"][0]["content"] = (
+                                schema_msg + "\n\n" + call_params["messages"][0]["content"]
+                            )
                     if self.provider not in ("lmstudio", "ollama"):
                         # LM Studio and Ollama don't support json_object response format reliably
                         # We rely on the schema in the system message instead
@@ -1013,20 +917,18 @@ class LLMProvider:
                 tool_calls: list[LLMToolCall] = []
 
                 if response.candidates and response.candidates[0].content:
-                    parts = response.candidates[0].content.parts
-                    if parts:
-                        for part in parts:
-                            if hasattr(part, "text") and part.text:
-                                content = part.text
-                            if hasattr(part, "function_call") and part.function_call:
-                                fc = part.function_call
-                                tool_calls.append(
-                                    LLMToolCall(
-                                        id=f"gemini_{len(tool_calls)}",
-                                        name=fc.name,
-                                        arguments=dict(fc.args) if fc.args else {},
-                                    )
+                    for part in response.candidates[0].content.parts:
+                        if hasattr(part, "text") and part.text:
+                            content = part.text
+                        if hasattr(part, "function_call") and part.function_call:
+                            fc = part.function_call
+                            tool_calls.append(
+                                LLMToolCall(
+                                    id=f"gemini_{len(tool_calls)}",
+                                    name=fc.name,
+                                    arguments=dict(fc.args) if fc.args else {},
                                 )
+                            )
 
                 finish_reason = "tool_calls" if tool_calls else "stop"
 
@@ -1602,12 +1504,6 @@ class LLMProvider:
         """Clear the recorded mock calls."""
         self._mock_calls = []
 
-    async def cleanup(self) -> None:
-        """Clean up resources (e.g., stop token refresh tasks)."""
-        if self._vertexai_refresher is not None:
-            await self._vertexai_refresher.stop()
-            logger.debug("Vertex AI token refresher stopped")
-
     @classmethod
     def for_memory(cls) -> "LLMProvider":
         """Create provider for memory operations from environment variables."""

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

@@ -2,8 +2,8 @@
 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
+1. search_reflections - User-curated summaries (highest quality)
+2. search_mental_models - Consolidated knowledge with freshness
 3. recall - Raw facts as ground truth
 """
 
@@ -20,12 +20,7 @@ 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 +28,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
 
@@ -58,7 +59,6 @@ def _normalize_tool_name(name: str) -> str:
     - '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.)
     """
@@ -70,11 +70,6 @@ def _normalize_tool_name(name: str) -> str:
     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
 
 
@@ -86,18 +81,6 @@ def _is_done_tool(name: str) -> bool:
 # 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.
@@ -110,33 +93,6 @@ def _clean_answer_text(text: str) -> str:
     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,
@@ -186,55 +142,35 @@ 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(
             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},
             ],
@@ -253,12 +189,6 @@ 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
 
@@ -272,8 +202,8 @@ async def run_reflect_agent(
     bank_id: str,
     query: str,
     bank_profile: dict[str, Any],
+    search_reflections_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
     search_mental_models_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
-    search_observations_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
     recall_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
     expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
     context: str | None = None,
@@ -281,15 +211,13 @@ async def run_reflect_agent(
     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
+    1. search_reflections - User-curated summaries (try first)
+    2. search_mental_models - Consolidated knowledge with freshness
     3. recall - Raw facts as ground truth
 
     Args:
@@ -297,8 +225,8 @@ async def run_reflect_agent(
         bank_id: Bank identifier
         query: Question to answer
         bank_profile: Bank profile with name and mission
+        search_reflections_fn: Tool callback for searching reflections (query, max_results) -> result
         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
         recall_fn: Tool callback for recall (query, max_tokens) -> result
         expand_fn: Tool callback for expand (memory_ids, depth) -> result
         context: Optional additional context
@@ -323,9 +251,7 @@ async def run_reflect_agent(
     tools = get_reflect_tools(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},
@@ -344,8 +270,8 @@ async def run_reflect_agent(
 
     # Track available IDs for validation (prevents hallucinated citations)
     available_memory_ids: set[str] = set()
+    available_reflection_ids: set[str] = set()
     available_mental_model_ids: set[str] = set()
-    available_observation_ids: set[str] = set()
 
     def _get_llm_trace() -> list[LLMCall]:
         return [
@@ -468,7 +394,7 @@ async def run_reflect_agent(
             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)
+                bool(available_memory_ids) or bool(available_reflection_ids) or bool(available_mental_model_ids)
             )
             if not has_gathered_evidence and iteration < max_iterations - 1:
                 continue
@@ -593,7 +519,7 @@ async def run_reflect_agent(
         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)
+                bool(available_memory_ids) or bool(available_reflection_ids) or bool(available_mental_model_ids)
             )
             if not has_gathered_evidence and iteration < max_iterations - 1:
                 # Add assistant message and fake tool result asking for evidence
@@ -610,7 +536,7 @@ async def run_reflect_agent(
                         "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 search for information first. Use search_reflections(), search_mental_models(), or recall() before providing your final answer."
                             }
                         ),
                     }
@@ -621,8 +547,8 @@ async def run_reflect_agent(
             return await _process_done_tool(
                 done_call,
                 available_memory_ids,
+                available_reflection_ids,
                 available_mental_model_ids,
-                available_observation_ids,
                 iteration + 1,
                 total_tools_called,
                 tool_trace,
@@ -650,8 +576,8 @@ async def run_reflect_agent(
             tool_tasks = [
                 _execute_tool_with_timing(
                     tc,
+                    search_reflections_fn,
                     search_mental_models_fn,
-                    search_observations_fn,
                     recall_fn,
                     expand_fn,
                 )
@@ -680,6 +606,15 @@ async def run_reflect_agent(
                     )
 
                 # Track available IDs from tool results (only for successful responses)
+                if (
+                    normalized_tool_name == "search_reflections"
+                    and isinstance(output, dict)
+                    and "reflections" in output
+                ):
+                    for reflection in output["reflections"]:
+                        if "id" in reflection:
+                            available_reflection_ids.add(reflection["id"])
+
                 if (
                     normalized_tool_name == "search_mental_models"
                     and isinstance(output, dict)
@@ -689,15 +624,6 @@ async def run_reflect_agent(
                         if "id" in mm:
                             available_mental_model_ids.add(mm["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:
                     for memory in output["memories"]:
                         if "id" in memory:
@@ -717,17 +643,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
                     )
                 )
 
@@ -777,8 +695,8 @@ def _tool_call_to_dict(tc: "LLMToolCall") -> dict[str, Any]:
 async def _process_done_tool(
     done_call: "LLMToolCall",
     available_memory_ids: set[str],
+    available_reflection_ids: set[str],
     available_mental_model_ids: set[str],
-    available_observation_ids: set[str],
     iterations: int,
     total_tools_called: int,
     tool_trace: list[ToolCall],
@@ -793,16 +711,14 @@ 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)
     used_memory_ids = [mid for mid in args.get("memory_ids", []) if mid in available_memory_ids]
+    used_reflection_ids = [rid for rid in args.get("reflection_ids", []) if rid in available_reflection_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]
 
     # Generate structured output if schema provided
     structured_output = None
@@ -828,16 +744,16 @@ async def _process_done_tool(
         llm_trace=llm_trace,
         usage=final_usage,
         used_memory_ids=used_memory_ids,
+        used_reflection_ids=used_reflection_ids,
         used_mental_model_ids=used_mental_model_ids,
-        used_observation_ids=used_observation_ids,
         directives_applied=directives_applied,
     )
 
 
 async def _execute_tool_with_timing(
     tc: "LLMToolCall",
+    search_reflections_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
     search_mental_models_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
-    search_observations_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
     recall_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
     expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
 ) -> tuple[dict[str, Any], int]:
@@ -846,8 +762,8 @@ async def _execute_tool_with_timing(
     result = await _execute_tool(
         tc.name,
         tc.arguments,
+        search_reflections_fn,
         search_mental_models_fn,
-        search_observations_fn,
         recall_fn,
         expand_fn,
     )
@@ -858,8 +774,8 @@ async def _execute_tool_with_timing(
 async def _execute_tool(
     tool_name: str,
     args: dict[str, Any],
+    search_reflections_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
     search_mental_models_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
-    search_observations_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
     recall_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
     expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
 ) -> dict[str, Any]:
@@ -867,19 +783,19 @@ async def _execute_tool(
     # Normalize tool name for various LLM output formats
     tool_name = _normalize_tool_name(tool_name)
 
-    if tool_name == "search_mental_models":
+    if tool_name == "search_reflections":
+        query = args.get("query")
+        if not query:
+            return {"error": "search_reflections requires a query parameter"}
+        max_results = args.get("max_results") or 5
+        return await search_reflections_fn(query, max_results)
+
+    elif 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)
-
-    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)
+        return await search_mental_models_fn(query, max_tokens)
 
     elif tool_name == "recall":
         query = args.get("query")
@@ -901,12 +817,12 @@ 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":
+    if tool_name == "search_reflections":
         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":
+    elif tool_name == "search_mental_models":
         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)
@@ -925,9 +841,9 @@ 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", [])
+        reflection_ids = args.get("reflection_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)})"
+            f"(answer={answer_preview}, mem={len(memory_ids)}, ref={len(reflection_ids)}, mm={len(mental_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")
@@ -72,7 +94,7 @@ class DirectiveInfo(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 TokenUsageSummary(BaseModel):
@@ -98,12 +120,12 @@ class ReflectAgentResult(BaseModel):
         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_reflection_ids: list[str] = Field(
+        default_factory=list, description="Validated reflection 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"
-    )
     directives_applied: list[DirectiveInfo] = Field(
         default_factory=list, description="Directive mental models that affected this reflection"
     )

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

@@ -2,8 +2,8 @@
 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
+1. search_reflections - User-curated summaries (highest quality)
+2. search_mental_models - Consolidated knowledge with freshness awareness
 3. recall - Raw facts as ground truth fallback
 """
 
@@ -125,23 +125,21 @@ 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,
+    has_reflections: bool = False,
 ) -> 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
+    1. search_reflections - User-curated summaries (try first, if available)
+    2. search_mental_models - Consolidated knowledge with freshness
     3. recall - Raw facts as ground truth
 
     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.
+        has_reflections: Whether the bank has any reflections (skip if not)
     """
     name = bank_profile.get("name", "Assistant")
     mission = bank_profile.get("mission", "")
@@ -178,25 +176,25 @@ def build_system_prompt_for_tools(
     )
 
     # Build retrieval levels based on what's available
-    if has_mental_models:
+    if has_reflections:
         parts.extend(
             [
                 "You have access to THREE levels of knowledge. Use them in this order:",
                 "",
-                "### 1. MENTAL MODELS (search_mental_models) - Try First",
+                "### 1. REFLECTIONS (search_reflections) - 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",
+                "- If a relevant reflection 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",
+                "### 2. MENTAL MODELS (search_mental_models) - 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",
+                "- Use when: no reflections/models exist, they're stale, or you need specific details",
                 "- This is the source of truth that other levels are built from",
                 "",
             ]
@@ -206,15 +204,15 @@ def build_system_prompt_for_tools(
             [
                 "You have access to TWO levels of knowledge. Use them in this order:",
                 "",
-                "### 1. OBSERVATIONS (search_observations) - Try First",
+                "### 1. MENTAL MODELS (search_mental_models) - 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",
+                "- Use when: no mental models exist, they're stale, or you need specific details",
+                "- This is the source of truth that mental models are built from",
                 "",
             ]
         )
@@ -232,57 +230,16 @@ def build_system_prompt_for_tools(
             "",
             "Think: What ENTITIES and CONCEPTS does this question involve? Search for each separately.",
             "",
+            "## 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:
+    if has_reflections:
         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",
+                "1. First, try search_reflections() - check if a curated summary exists",
+                "2. If no reflection or it's stale, try search_mental_models() for consolidated knowledge",
+                "3. If mental models 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",
             ]
@@ -290,8 +247,8 @@ def build_system_prompt_for_tools(
     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",
+                "1. First, try search_mental_models() - check for consolidated knowledge",
+                "2. If mental models 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",
             ]
@@ -304,7 +261,7 @@ def build_system_prompt_for_tools(
             "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 IDs ONLY in the memory_ids/reflection_ids/mental_model_ids arrays, not in the answer",
         ]
     )
 
@@ -399,8 +356,8 @@ def build_agent_prompt(
         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"
+            "1. Try search_reflections() first for curated summaries\n"
+            "2. Try search_mental_models() for consolidated knowledge\n"
             "3. Use recall() for specific details or to verify stale data"
         )
 

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

@@ -2,8 +2,8 @@
 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
+1. search_reflections - User-curated summaries (highest quality)
+2. search_mental_models - Consolidated knowledge with freshness
 3. recall - Raw facts as ground truth
 """
 
@@ -20,11 +20,11 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-# Observation is considered stale if not updated in this many days
+# Mental model is considered stale if not updated in this many days
 STALE_THRESHOLD_DAYS = 7
 
 
-async def tool_search_mental_models(
+async def tool_search_reflections(
     conn: "Connection",
     bank_id: str,
     query: str,
@@ -35,9 +35,9 @@ async def tool_search_mental_models(
     exclude_ids: list[str] | None = None,
 ) -> dict[str, Any]:
     """
-    Search user-curated mental models by semantic similarity.
+    Search user-curated reflections by semantic similarity.
 
-    Mental models are high-quality, manually created summaries about specific topics.
+    Reflections are high-quality, manually created summaries about specific topics.
     They should be searched FIRST as they represent the most reliable synthesized knowledge.
 
     Args:
@@ -45,13 +45,13 @@ async def tool_search_mental_models(
         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
+        max_results: Maximum number of reflections to return
+        tags: Optional tags to filter reflections
         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)
+        exclude_ids: Optional list of reflection IDs to exclude (e.g., when refreshing a reflection)
 
     Returns:
-        Dict with matching mental models including content and freshness info
+        Dict with matching reflections including content and freshness info
     """
     from ..memory_engine import fq_table
 
@@ -69,18 +69,18 @@ async def tool_search_mental_models(
         next_param += 1
 
     if exclude_ids:
-        filters += f" AND id != ALL(${next_param}::text[])"
+        filters += f" AND id != ALL(${next_param}::uuid[])"
         params.append(exclude_ids)
         next_param += 1
 
-    # Search mental models by embedding similarity
+    # Search reflections by embedding similarity
     rows = await conn.fetch(
         f"""
         SELECT
-            id, name, content,
+            id, name, content, reflect_response,
             tags, created_at, last_refreshed_at,
             1 - (embedding <=> $2::vector) as relevance
-        FROM {fq_table("mental_models")}
+        FROM {fq_table("reflections")}
         WHERE bank_id = $1 AND embedding IS NOT NULL {filters}
         ORDER BY embedding <=> $2::vector
         LIMIT $3
@@ -89,7 +89,7 @@ async def tool_search_mental_models(
     )
 
     now = datetime.now(timezone.utc)
-    mental_models = []
+    reflections = []
 
     for row in rows:
         last_refreshed_at = row["last_refreshed_at"]
@@ -102,11 +102,12 @@ async def tool_search_mental_models(
             age = now - last_refreshed_at
             is_stale = age > timedelta(days=STALE_THRESHOLD_DAYS)
 
-        mental_models.append(
+        reflections.append(
             {
                 "id": str(row["id"]),
                 "name": row["name"],
                 "content": row["content"],
+                "reflect_response": row["reflect_response"],
                 "tags": row["tags"] or [],
                 "relevance": round(row["relevance"], 4),
                 "updated_at": last_refreshed_at.isoformat() if last_refreshed_at else None,
@@ -116,12 +117,12 @@ async def tool_search_mental_models(
 
     return {
         "query": query,
-        "count": len(mental_models),
-        "mental_models": mental_models,
+        "count": len(reflections),
+        "reflections": reflections,
     }
 
 
-async def tool_search_observations(
+async def tool_search_mental_models(
     memory_engine: "MemoryEngine",
     bank_id: str,
     query: str,
@@ -133,9 +134,9 @@ async def tool_search_observations(
     pending_consolidation: int = 0,
 ) -> dict[str, Any]:
     """
-    Search consolidated observations using recall with include_observations.
+    Search consolidated mental models using recall with include_mental_models.
 
-    Observations are auto-generated from memories. Returns freshness info
+    Mental models are auto-generated from memories. Returns freshness info
     so the agent knows if it should also verify with recall().
 
     Args:
@@ -144,22 +145,22 @@ async def tool_search_observations(
         query: Search query
         request_context: Request context for authentication
         max_tokens: Maximum tokens for results (default 5000)
-        tags: Optional tags to filter observations
+        tags: Optional tags to filter models
         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
+        Dict with matching mental models including freshness info
     """
     from ..memory_engine import fq_table
 
-    # Use recall to search observations (they come back in results field when fact_type=["observation"])
+    # Use recall to search mental models (they come back in results field when fact_type=["mental_model"])
     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
+        fact_type=["mental_model"],  # Only retrieve mental models
+        max_tokens=max_tokens,  # Token budget controls how many mental models are returned
         enable_trace=False,
         request_context=request_context,
         tags=tags,
@@ -168,29 +169,29 @@ async def tool_search_observations(
         _quiet=True,
     )
 
-    observations = []
+    mental_models = []
 
-    # When fact_type=["observation"], results come back in `results` field as MemoryFact objects
+    # When fact_type=["mental_model"], 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]
+        mm_ids = [m.id for m in result.results]
 
-        # Fetch proof_count and source_memory_ids for these observations
+        # Fetch proof_count and source_memory_ids for these mental models
         pool = await memory_engine._get_pool()
         async with pool.acquire() as conn:
-            obs_rows = await conn.fetch(
+            mm_rows = await conn.fetch(
                 f"""
                 SELECT id, proof_count, source_memory_ids
                 FROM {fq_table("memory_units")}
                 WHERE id = ANY($1::uuid[])
                 """,
-                obs_ids,
+                mm_ids,
             )
-            obs_data = {str(row["id"]): row for row in obs_rows}
+            mm_data = {str(row["id"]): row for row in mm_rows}
 
         for m in result.results:
             # Get additional data from DB lookup
-            extra = obs_data.get(m.id, {})
+            extra = mm_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
@@ -203,7 +204,7 @@ async def tool_search_observations(
                 is_stale = True
                 staleness_reason = f"{pending_consolidation} memories pending consolidation"
 
-            observations.append(
+            mental_models.append(
                 {
                     "id": str(m.id),
                     "text": m.text,
@@ -225,8 +226,8 @@ async def tool_search_observations(
 
     return {
         "query": query,
-        "count": len(observations),
-        "observations": observations,
+        "count": len(mental_models),
+        "mental_models": mental_models,
         "freshness": freshness,
     }
 
@@ -246,7 +247,7 @@ 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.
+    Use when reflections/mental models don't exist, are stale, or need verification.
 
     Args:
         memory_engine: Memory engine instance
@@ -265,7 +266,7 @@ 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 and mental_models
         max_tokens=max_tokens,
         enable_trace=False,
         request_context=request_context,

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

@@ -3,69 +3,61 @@ 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
+1. search_reflections - User-curated summaries (highest quality, if applicable)
+2. search_mental_models - Consolidated knowledge with freshness awareness
 3. recall - Raw facts (world/experience) as ground truth fallback
 """
 
 # Tool definitions in OpenAI format
 
+TOOL_SEARCH_REFLECTIONS = {
+    "type": "function",
+    "function": {
+        "name": "search_reflections",
+        "description": (
+            "Search user-curated reflections (summaries). These are high-quality, manually created "
+            "summaries about specific topics. Use FIRST when the question might be covered by an "
+            "existing reflection. Returns reflections with their content and last refresh time."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Search query to find relevant reflections",
+                },
+                "max_results": {
+                    "type": "integer",
+                    "description": "Maximum number of reflections to return (default 5)",
+                },
+            },
+            "required": ["query"],
+        },
+    },
+}
+
 TOOL_SEARCH_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."
+            "Search consolidated mental models (auto-generated knowledge). These are automatically "
+            "synthesized from memories. Returns models with freshness info (updated_at, is_stale). "
+            "If a model is STALE, you should ALSO use recall() to verify with current facts."
         ),
         "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"],
-        },
-    },
-}
-
-TOOL_SEARCH_OBSERVATIONS = {
-    "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."
-        ),
-        "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 observations",
-                },
                 "max_tokens": {
                     "type": "integer",
                     "description": "Maximum tokens for results (default 5000). Use higher values for broader searches.",
                 },
             },
-            "required": ["reason", "query"],
+            "required": ["query"],
         },
     },
 }
@@ -83,10 +75,6 @@ TOOL_RECALL = {
         "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 +84,7 @@ TOOL_RECALL = {
                     "description": "Optional limit on result size (default 2048). Use higher values for broader searches.",
                 },
             },
-            "required": ["reason", "query"],
+            "required": ["query"],
         },
     },
 }
@@ -109,10 +97,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 +108,7 @@ TOOL_EXPAND = {
                     "description": "chunk: surrounding text chunk, document: full source document",
                 },
             },
-            "required": ["reason", "memory_ids", "depth"],
+            "required": ["memory_ids", "depth"],
         },
     },
 }
@@ -146,16 +130,16 @@ TOOL_DONE_ANSWER = {
                     "items": {"type": "string"},
                     "description": "Array of memory IDs that support your answer (put IDs here, NOT in answer text)",
                 },
+                "reflection_ids": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Array of reflection IDs that support your answer",
+                },
                 "mental_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"],
         },
@@ -197,16 +181,16 @@ 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)",
                     },
+                    "reflection_ids": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Array of reflection IDs that support your answer",
+                    },
                     "mental_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]...'",
@@ -223,8 +207,8 @@ def get_reflect_tools(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
+    1. search_reflections - User-curated summaries (try first)
+    2. search_mental_models - Consolidated knowledge with freshness
     3. recall - Raw facts as ground truth
 
     Args:
@@ -235,8 +219,8 @@ def get_reflect_tools(directive_rules: list[str] | None = None) -> list[dict]:
         List of tool definitions in OpenAI format
     """
     tools = [
+        TOOL_SEARCH_REFLECTIONS,
         TOOL_SEARCH_MENTAL_MODELS,
-        TOOL_SEARCH_OBSERVATIONS,
         TOOL_RECALL,
         TOOL_EXPAND,
     ]

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", "mental_model"])
 
 
 class LLMToolCall(BaseModel):
@@ -36,7 +36,6 @@ 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 +49,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 +65,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,23 +168,23 @@ 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)."""
+class MentalModelResult(BaseModel):
+    """A mental model result from recall."""
 
-    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")
+    id: str = Field(description="Unique mental model ID")
+    text: str = Field(description="The mental model text")
+    proof_count: int = Field(description="Number of facts supporting this mental model")
     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"
+        default_factory=list, description="IDs of facts that contribute to this mental model"
     )
 
 
-class MentalModelResult(BaseModel):
-    """A mental model result from recall (stored reflect response)."""
+class ReflectionResult(BaseModel):
+    """A reflection result from recall."""
 
-    id: str = Field(description="Unique mental model ID")
+    id: str = Field(description="Unique reflection 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")
@@ -254,14 +253,7 @@ class ReflectResult(BaseModel):
                     ],
                     "experience": [],
                     "opinion": [],
-                    "mental_models": [],
-                    "directives": [
-                        {
-                            "id": "directive-123",
-                            "name": "Response Style",
-                            "rules": ["Always be concise"],
-                        }
-                    ],
+                    "mental-models": [],
                 },
                 "new_opinions": ["Machine learning has great potential in healthcare"],
                 "structured_output": {"summary": "ML in healthcare", "confidence": 0.9},
@@ -271,8 +263,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, mental-models)"
     )
     new_opinions: list[str] = Field(default_factory=list, description="List of newly formed opinions during reflection")
     structured_output: dict[str, Any] | None = Field(

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

@@ -432,15 +432,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.
 
 {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 +507,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 +533,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.
@@ -701,12 +680,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 +698,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 +717,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
@@ -782,28 +747,12 @@ Text:
     usage = TokenUsage()  # Track cumulative usage across retries
     for attempt in range(max_retries):
         try:
-            # Use retain-specific overrides if set, otherwise fall back to global LLM config
-            max_retries = (
-                config.retain_llm_max_retries if config.retain_llm_max_retries is not None else config.llm_max_retries
-            )
-            initial_backoff = (
-                config.retain_llm_initial_backoff
-                if config.retain_llm_initial_backoff is not None
-                else config.llm_initial_backoff
-            )
-            max_backoff = (
-                config.retain_llm_max_backoff if config.retain_llm_max_backoff is not None else config.llm_max_backoff
-            )
-
             extraction_response_json, call_usage = await llm_config.call(
                 messages=[{"role": "system", "content": prompt}, {"role": "user", "content": user_message}],
                 response_format=response_schema,
                 scope="memory_extract_facts",
                 temperature=0.1,
                 max_completion_tokens=config.retain_max_completion_tokens,
-                max_retries=max_retries,
-                initial_backoff=initial_backoff,
-                max_backoff=max_backoff,
                 skip_validation=True,  # Get raw JSON, we'll validate leniently
                 return_usage=True,
             )

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/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/engine/vertexai_token_refresher.py

@@ -1,120 +0,0 @@
-"""Vertex AI token refresher with background refresh and caching."""
-
-import asyncio
-import logging
-import threading
-from datetime import datetime
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-
-class VertexAITokenRefresher:
-    """
-    Background token refresher for Vertex AI.
-
-    Refreshes Google Cloud access tokens every 50 minutes to ensure they don't expire (60-min default).
-    Thread-safe token caching for concurrent access from multiple async tasks.
-    """
-
-    def __init__(self, credentials: Any, project_id: str, region: str):
-        """
-        Initialize the token refresher.
-
-        Args:
-            credentials: Google Cloud credentials object (from google.auth.default or service_account)
-            project_id: GCP project ID
-            region: GCP region (e.g., "us-central1")
-        """
-        self._credentials = credentials
-        self._project_id = project_id
-        self._region = region
-
-        # Thread-safe token cache
-        self._token: str | None = None
-        self._token_expiry: datetime | None = None
-        self._lock = threading.Lock()
-
-        # Background refresh task
-        self._refresh_task: asyncio.Task | None = None
-        self._stop_event = asyncio.Event()
-
-        # Initial token fetch (synchronous, must complete before returning)
-        self._refresh_token_sync()
-
-    def _refresh_token_sync(self) -> None:
-        """Synchronously refresh the token (thread-safe)."""
-        try:
-            import google.auth.transport.requests
-
-            request = google.auth.transport.requests.Request()
-            self._credentials.refresh(request)
-
-            with self._lock:
-                self._token = self._credentials.token
-                self._token_expiry = self._credentials.expiry
-
-            logger.debug(f"Vertex AI token refreshed, expires at {self._token_expiry}")
-        except Exception as e:
-            logger.error(f"Failed to refresh Vertex AI token: {e}")
-            raise
-
-    async def _refresh_loop(self) -> None:
-        """Background refresh loop (runs every 50 minutes)."""
-        while not self._stop_event.is_set():
-            try:
-                # Wait 50 minutes or until stop event
-                await asyncio.wait_for(self._stop_event.wait(), timeout=50 * 60)
-                # If we get here, stop was signaled
-                break
-            except asyncio.TimeoutError:
-                # 50 minutes passed, refresh token
-                try:
-                    loop = asyncio.get_running_loop()
-                    await loop.run_in_executor(None, self._refresh_token_sync)
-                except Exception as e:
-                    logger.error(f"Background token refresh failed: {e}")
-                    # Continue loop - next API call will fail with auth error
-
-    def start_refresh_task(self) -> None:
-        """Start the background refresh task."""
-        if self._refresh_task is None or self._refresh_task.done():
-            self._refresh_task = asyncio.create_task(self._refresh_loop())
-            logger.info("Vertex AI token refresh task started (refreshes every 50 minutes)")
-
-    async def stop(self) -> None:
-        """Stop the background refresh task."""
-        if self._refresh_task is not None and not self._refresh_task.done():
-            self._stop_event.set()
-            try:
-                await asyncio.wait_for(self._refresh_task, timeout=5.0)
-            except asyncio.TimeoutError:
-                logger.warning("Vertex AI token refresh task did not stop within 5 seconds")
-            logger.info("Vertex AI token refresh task stopped")
-
-    def get_token(self) -> str:
-        """
-        Get current access token (thread-safe).
-
-        Returns:
-            Current Google Cloud access token
-
-        Raises:
-            RuntimeError: If token is not available
-        """
-        with self._lock:
-            if self._token is None:
-                raise RuntimeError("Vertex AI token not available")
-            return self._token
-
-    def get_base_url(self) -> str:
-        """
-        Get the Vertex AI OpenAI-compatible endpoint URL.
-
-        Returns:
-            Base URL for Vertex AI OpenAI API
-        """
-        return (
-            f"https://{self._region}-aiplatform.googleapis.com/v1beta1/"
-            f"projects/{self._project_id}/locations/{self._region}/endpoints/openapi"
-        )

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

@@ -1,6 +1,5 @@
 """Built-in tenant extension implementations."""
 
-from hindsight_api.config import get_config
 from hindsight_api.extensions.tenant import AuthenticationError, Tenant, TenantContext, TenantExtension
 from hindsight_api.models import RequestContext
 
@@ -11,13 +10,11 @@ class ApiKeyTenantExtension(TenantExtension):
 
     This is a simple implementation that:
     1. Validates the API key matches HINDSIGHT_API_TENANT_API_KEY
-    2. Returns the configured schema (HINDSIGHT_API_DATABASE_SCHEMA, default 'public')
-       for all authenticated requests
+    2. Returns 'public' as the schema for all authenticated requests
 
     Configuration:
         HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension
         HINDSIGHT_API_TENANT_API_KEY=your-secret-key
-        HINDSIGHT_API_DATABASE_SCHEMA=your-schema (optional, defaults to 'public')
 
     For multi-tenant setups with separate schemas per tenant, implement a custom
     TenantExtension that looks up the schema based on the API key or token claims.
@@ -30,11 +27,11 @@ class ApiKeyTenantExtension(TenantExtension):
             raise ValueError("HINDSIGHT_API_TENANT_API_KEY is required when using ApiKeyTenantExtension")
 
     async def authenticate(self, context: RequestContext) -> TenantContext:
-        """Validate API key and return configured schema context."""
+        """Validate API key and return public schema context."""
         if context.api_key != self.expected_api_key:
             raise AuthenticationError("Invalid API key")
-        return TenantContext(schema_name=get_config().database_schema)
+        return TenantContext(schema_name="public")
 
     async def list_tenants(self) -> list[Tenant]:
-        """Return configured schema for single-tenant setup."""
-        return [Tenant(schema=get_config().database_schema)]
+        """Return public schema for single-tenant setup."""
+        return [Tenant(schema="public")]

hindsight-api/hindsight_api/main.py

@@ -170,56 +170,31 @@ def main():
     if args.log_level != config.log_level:
         config = HindsightConfig(
             database_url=config.database_url,
-            database_schema=config.database_schema,
             llm_provider=config.llm_provider,
             llm_api_key=config.llm_api_key,
             llm_model=config.llm_model,
             llm_base_url=config.llm_base_url,
             llm_max_concurrent=config.llm_max_concurrent,
-            llm_max_retries=config.llm_max_retries,
-            llm_initial_backoff=config.llm_initial_backoff,
-            llm_max_backoff=config.llm_max_backoff,
             llm_timeout=config.llm_timeout,
-            llm_vertexai_project_id=config.llm_vertexai_project_id,
-            llm_vertexai_region=config.llm_vertexai_region,
-            llm_vertexai_service_account_key=config.llm_vertexai_service_account_key,
             retain_llm_provider=config.retain_llm_provider,
             retain_llm_api_key=config.retain_llm_api_key,
             retain_llm_model=config.retain_llm_model,
             retain_llm_base_url=config.retain_llm_base_url,
-            retain_llm_max_concurrent=config.retain_llm_max_concurrent,
-            retain_llm_max_retries=config.retain_llm_max_retries,
-            retain_llm_initial_backoff=config.retain_llm_initial_backoff,
-            retain_llm_max_backoff=config.retain_llm_max_backoff,
-            retain_llm_timeout=config.retain_llm_timeout,
             reflect_llm_provider=config.reflect_llm_provider,
             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,
-            reflect_llm_max_concurrent=config.reflect_llm_max_concurrent,
-            reflect_llm_max_retries=config.reflect_llm_max_retries,
-            reflect_llm_initial_backoff=config.reflect_llm_initial_backoff,
-            reflect_llm_max_backoff=config.reflect_llm_max_backoff,
-            reflect_llm_timeout=config.reflect_llm_timeout,
             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,
-            consolidation_llm_max_concurrent=config.consolidation_llm_max_concurrent,
-            consolidation_llm_max_retries=config.consolidation_llm_max_retries,
-            consolidation_llm_initial_backoff=config.consolidation_llm_initial_backoff,
-            consolidation_llm_max_backoff=config.consolidation_llm_max_backoff,
-            consolidation_llm_timeout=config.consolidation_llm_timeout,
             embeddings_provider=config.embeddings_provider,
             embeddings_local_model=config.embeddings_local_model,
-            embeddings_local_force_cpu=config.embeddings_local_force_cpu,
             embeddings_tei_url=config.embeddings_tei_url,
             embeddings_openai_base_url=config.embeddings_openai_base_url,
             embeddings_cohere_base_url=config.embeddings_cohere_base_url,
             reranker_provider=config.reranker_provider,
             reranker_local_model=config.reranker_local_model,
-            reranker_local_force_cpu=config.reranker_local_force_cpu,
-            reranker_local_max_concurrent=config.reranker_local_max_concurrent,
             reranker_tei_url=config.reranker_tei_url,
             reranker_tei_batch_size=config.reranker_tei_batch_size,
             reranker_tei_max_concurrent=config.reranker_tei_max_concurrent,
@@ -234,15 +209,16 @@ 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,
+            enable_mental_models=config.enable_mental_models,
+            consolidation_similarity_threshold=config.consolidation_similarity_threshold,
             consolidation_batch_size=config.consolidation_batch_size,
-            consolidation_max_tokens=config.consolidation_max_tokens,
             skip_llm_verification=config.skip_llm_verification,
             lazy_reranker=config.lazy_reranker,
             run_migrations_on_startup=config.run_migrations_on_startup,
@@ -367,7 +343,6 @@ def main():
     # Start idle checker in daemon mode
     if idle_middleware is not None:
         # Start the idle checker in a background thread with its own event loop
-        import logging
         import threading
 
         def run_idle_checker():
@@ -378,12 +353,12 @@ def main():
                 loop = asyncio.new_event_loop()
                 asyncio.set_event_loop(loop)
                 loop.run_until_complete(idle_middleware._check_idle())
-            except Exception as e:
-                logging.error(f"Idle checker error: {e}", exc_info=True)
+            except Exception:
+                pass
 
         threading.Thread(target=run_idle_checker, daemon=True).start()
 
-    uvicorn.run(**uvicorn_config)
+    uvicorn.run(**uvicorn_config)  # type: ignore[invalid-argument-type] - dict kwargs
 
 
 if __name__ == "__main__":

hindsight-api/hindsight_api/pg0.py

@@ -40,7 +40,7 @@ class EmbeddedPostgres:
             # Only set port if explicitly specified
             if self.port is not None:
                 kwargs["port"] = self.port
-            self._pg0 = Pg0(**kwargs)
+            self._pg0 = Pg0(**kwargs)  # type: ignore[invalid-argument-type] - dict kwargs
         return self._pg0
 
     async def start(self, max_retries: int = 5, retry_delay: float = 4.0) -> str:

hindsight-api/hindsight_api/worker/main.py

@@ -183,25 +183,21 @@ def main():
 
         from ..extensions import TenantExtension, load_extension
 
-        # Load tenant extension BEFORE creating MemoryEngine so it can
-        # set correct schema context during task execution. Without this,
-        # _authenticate_tenant sees no extension and resets schema to "public",
-        # causing worker writes to land in the wrong schema.
-        tenant_extension = load_extension("TENANT", TenantExtension)
-
         # Initialize MemoryEngine
         # Workers use SyncTaskBackend because they execute tasks directly,
         # they don't need to store tasks (they poll from DB)
         memory = MemoryEngine(
             run_migrations=False,  # Workers don't run migrations
             task_backend=SyncTaskBackend(),
-            tenant_extension=tenant_extension,
         )
 
         await memory.initialize()
 
         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:

hindsight-api/hindsight_api/worker/poller.py

@@ -261,9 +261,6 @@ class WorkerPoller:
         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")

hindsight-api/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hindsight-api"
-version = "0.4.2"
+version = "0.3.0"
 description = "Hindsight: Agent Memory That Works Like Human Memory"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -34,7 +34,6 @@ dependencies = [
     "opentelemetry-exporter-prometheus>=0.41b0",
     "dateparser>=1.2.2",
     "google-genai>=1.0.0",
-    "google-auth>=2.0.0",
     "anthropic>=0.40.0",
     "typer>=0.9.0",
     "cohere>=5.0.0",
@@ -142,11 +141,6 @@ known-third-party = ["alembic"]
 quote-style = "double"
 indent-style = "space"
 
-[tool.uv]
-# Allow uv to search all configured indexes for packages, not just the first one
-# This prevents dependency resolution failures when using pytorch index + PyPI
-index-strategy = "unsafe-best-match"
-
 [tool.ty]
 # Type checking configuration
 # ty is an extremely fast Python type checker from Astral (same team as ruff/uv)

hindsight-api/tests/test_http_api_integration.py

@@ -1063,38 +1063,3 @@ async def test_retain_async_no_usage(api_client):
 
     # Usage should be None for async operations
     assert result.get("usage") is None, "Async retain should not include usage"
-
-
-@pytest.mark.asyncio
-async def test_version_endpoint_returns_correct_version(api_client):
-    """Test that the /version endpoint returns the correct API version.
-
-    The version should match the __version__ defined in hindsight_api.__init__.py
-    and should not be a hardcoded string.
-    """
-    from hindsight_api import __version__
-
-    # Call the /version endpoint
-    response = await api_client.get("/version")
-    assert response.status_code == 200
-    result = response.json()
-
-    # Verify response structure
-    assert "api_version" in result, "Response should include 'api_version' field"
-    assert "features" in result, "Response should include 'features' field"
-
-    # Verify the version matches the package version
-    assert result["api_version"] == __version__, (
-        f"API version should be {__version__}, got {result['api_version']}"
-    )
-
-    # Verify features field structure
-    features = result["features"]
-    assert "observations" in features
-    assert "mcp" in features
-    assert "worker" in features
-    assert isinstance(features["observations"], bool)
-    assert isinstance(features["mcp"], bool)
-    assert isinstance(features["worker"], bool)
-
-    print(f"Version endpoint returned: api_version={result['api_version']}, features={features}")

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,8 +241,8 @@ class TestReflectToolSchemas:
         tools = get_reflect_tools()
 
         tool_names = [t["function"]["name"] for t in tools]
+        assert "search_reflections" in tool_names
         assert "search_mental_models" in tool_names
-        assert "search_observations" in tool_names
         assert "recall" in tool_names
         assert "expand" in tool_names
         assert "done" in tool_names
@@ -273,8 +273,8 @@ class TestReflectToolSchemas:
 
         assert "answer" in params
         assert "memory_ids" in params
-        assert "observation_ids" in params
         assert "mental_model_ids" in params
+        assert "reflection_ids" in params
 
 
 class TestLLMToolCallResult:

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_per_operation_llm_config.py

@@ -275,88 +275,3 @@ class TestReflectUsesReflectLLMConfig:
 
         # Verify it's different from the retain config
         assert engine._reflect_llm_config.model != engine._retain_llm_config.model
-
-
-class TestRetryAndBackoffConfiguration:
-    """Test retry and backoff configuration options."""
-
-    def test_global_retry_backoff_config_defaults(self):
-        """Test that global retry/backoff settings have correct defaults."""
-        from hindsight_api.config import get_config
-
-        config = get_config()
-
-        # Verify global defaults
-        assert config.llm_max_retries == 10
-        assert config.llm_initial_backoff == 1.0
-        assert config.llm_max_backoff == 60.0
-
-    def test_per_operation_retry_backoff_config_from_env(self):
-        """Test that per-operation retry/backoff settings are loaded from environment."""
-        from hindsight_api.config import clear_config_cache
-
-        # Set per-operation overrides
-        os.environ["HINDSIGHT_API_RETAIN_LLM_MAX_RETRIES"] = "3"
-        os.environ["HINDSIGHT_API_RETAIN_LLM_INITIAL_BACKOFF"] = "2.0"
-        os.environ["HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF"] = "120.0"
-        os.environ["HINDSIGHT_API_REFLECT_LLM_MAX_RETRIES"] = "5"
-        os.environ["HINDSIGHT_API_REFLECT_LLM_INITIAL_BACKOFF"] = "1.5"
-        os.environ["HINDSIGHT_API_REFLECT_LLM_MAX_BACKOFF"] = "90.0"
-
-        try:
-            clear_config_cache()
-            from hindsight_api.config import get_config
-
-            config = get_config()
-
-            # Verify retain overrides
-            assert config.retain_llm_max_retries == 3
-            assert config.retain_llm_initial_backoff == 2.0
-            assert config.retain_llm_max_backoff == 120.0
-
-            # Verify reflect overrides
-            assert config.reflect_llm_max_retries == 5
-            assert config.reflect_llm_initial_backoff == 1.5
-            assert config.reflect_llm_max_backoff == 90.0
-
-            # Verify global defaults remain unchanged
-            assert config.llm_max_retries == 10
-            assert config.llm_initial_backoff == 1.0
-            assert config.llm_max_backoff == 60.0
-        finally:
-            # Clean up
-            os.environ.pop("HINDSIGHT_API_RETAIN_LLM_MAX_RETRIES", None)
-            os.environ.pop("HINDSIGHT_API_RETAIN_LLM_INITIAL_BACKOFF", None)
-            os.environ.pop("HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF", None)
-            os.environ.pop("HINDSIGHT_API_REFLECT_LLM_MAX_RETRIES", None)
-            os.environ.pop("HINDSIGHT_API_REFLECT_LLM_INITIAL_BACKOFF", None)
-            os.environ.pop("HINDSIGHT_API_REFLECT_LLM_MAX_BACKOFF", None)
-            clear_config_cache()
-
-    def test_per_operation_retry_backoff_fallback_to_global(self):
-        """Test that per-operation settings fall back to global when not set."""
-        from hindsight_api.config import clear_config_cache, get_config
-
-        # Set only global values
-        os.environ["HINDSIGHT_API_LLM_MAX_RETRIES"] = "7"
-        os.environ["HINDSIGHT_API_LLM_INITIAL_BACKOFF"] = "3.0"
-        os.environ["HINDSIGHT_API_LLM_MAX_BACKOFF"] = "180.0"
-
-        try:
-            clear_config_cache()
-            config = get_config()
-
-            # Per-operation should be None (will fall back to global at runtime)
-            assert config.retain_llm_max_retries is None
-            assert config.retain_llm_initial_backoff is None
-            assert config.retain_llm_max_backoff is None
-
-            # Global values should be set
-            assert config.llm_max_retries == 7
-            assert config.llm_initial_backoff == 3.0
-            assert config.llm_max_backoff == 180.0
-        finally:
-            os.environ.pop("HINDSIGHT_API_LLM_MAX_RETRIES", None)
-            os.environ.pop("HINDSIGHT_API_LLM_INITIAL_BACKOFF", None)
-            os.environ.pop("HINDSIGHT_API_LLM_MAX_BACKOFF", None)
-            clear_config_cache()

hindsight-api/tests/test_reflect_agent.py

@@ -14,7 +14,6 @@ from hindsight_api.engine.reflect.agent import (
     _normalize_tool_name,
     _is_done_tool,
     _clean_answer_text,
-    _clean_done_answer,
     run_reflect_agent,
 )
 from hindsight_api.engine.response_models import LLMToolCall, LLMToolCallResult, TokenUsage
@@ -62,79 +61,6 @@ class TestCleanAnswerText:
         assert cleaned == "Summary of findings."
 
 
-class TestCleanDoneAnswer:
-    """Test cleanup of answer field from done() tool call that leaks structured output."""
-
-    def test_clean_answer_with_leaked_json_code_block(self):
-        """Answer with leaked JSON code block at the end should be cleaned."""
-        text = '''The user's favorite color is blue.
-
-```json
-{"observation_ids": ["obs-1", "obs-2"]}
-```'''
-        cleaned = _clean_done_answer(text)
-        assert cleaned == "The user's favorite color is blue."
-        assert "observation_ids" not in cleaned
-
-    def test_clean_answer_with_memory_ids_code_block(self):
-        """Answer with leaked memory_ids JSON code block should be cleaned."""
-        text = '''Here is the answer.
-
-```json
-{"memory_ids": ["mem-1"]}
-```'''
-        cleaned = _clean_done_answer(text)
-        assert cleaned == "Here is the answer."
-
-    def test_clean_answer_with_raw_json_object(self):
-        """Answer with raw JSON object containing IDs at the end should be cleaned."""
-        text = 'The answer is 42. {"observation_ids": ["obs-1"]}'
-        cleaned = _clean_done_answer(text)
-        assert cleaned == "The answer is 42."
-
-    def test_clean_answer_with_trailing_ids_pattern(self):
-        """Answer with 'observation_ids: [...]' pattern at the end should be cleaned."""
-        text = "This is the answer.\n\nobservation_ids: [\"obs-1\", \"obs-2\"]"
-        cleaned = _clean_done_answer(text)
-        assert cleaned == "This is the answer."
-
-    def test_clean_answer_with_memory_ids_equals(self):
-        """Answer with 'memory_ids = [...]' pattern at the end should be cleaned."""
-        text = "Answer text here.\nmemory_ids = [\"mem-1\"]"
-        cleaned = _clean_done_answer(text)
-        assert cleaned == "Answer text here."
-
-    def test_clean_normal_answer_unchanged(self):
-        """Normal answer without leaked output should be unchanged."""
-        text = "This is a normal answer about observation strategies."
-        cleaned = _clean_done_answer(text)
-        assert cleaned == text
-
-    def test_clean_empty_answer(self):
-        """Empty answer should return empty."""
-        assert _clean_done_answer("") == ""
-
-    def test_clean_answer_with_observation_word_in_content(self):
-        """The word 'observation' in regular text should not be stripped."""
-        text = "Based on my observation, the user prefers dark mode."
-        cleaned = _clean_done_answer(text)
-        assert cleaned == text
-
-    def test_clean_answer_multiline_with_markdown(self):
-        """Answer with markdown and leaked JSON at end should clean only the leak."""
-        text = '''Summary:
-- Point 1
-- Point 2
-
-```json
-{"mental_model_ids": ["mm-1"]}
-```'''
-        cleaned = _clean_done_answer(text)
-        assert "Point 1" in cleaned
-        assert "Point 2" in cleaned
-        assert "mental_model_ids" not in cleaned
-
-
 class TestToolNameNormalization:
     """Test tool name normalization for various LLM output formats."""
 
@@ -142,15 +68,15 @@ class TestToolNameNormalization:
         """Standard tool names should pass through unchanged."""
         assert _normalize_tool_name("done") == "done"
         assert _normalize_tool_name("recall") == "recall"
+        assert _normalize_tool_name("search_reflections") == "search_reflections"
         assert _normalize_tool_name("search_mental_models") == "search_mental_models"
-        assert _normalize_tool_name("search_observations") == "search_observations"
         assert _normalize_tool_name("expand") == "expand"
 
     def test_normalize_functions_prefix(self):
         """Tool names with 'functions.' prefix should be normalized."""
         assert _normalize_tool_name("functions.done") == "done"
         assert _normalize_tool_name("functions.recall") == "recall"
-        assert _normalize_tool_name("functions.search_mental_models") == "search_mental_models"
+        assert _normalize_tool_name("functions.search_reflections") == "search_reflections"
 
     def test_normalize_call_equals_prefix(self):
         """Tool names with 'call=' prefix should be normalized."""
@@ -161,13 +87,7 @@ class TestToolNameNormalization:
         """Tool names with 'call=functions.' prefix should be normalized."""
         assert _normalize_tool_name("call=functions.done") == "done"
         assert _normalize_tool_name("call=functions.recall") == "recall"
-        assert _normalize_tool_name("call=functions.search_observations") == "search_observations"
-
-    def test_normalize_special_token_suffix(self):
-        """Tool names with malformed special tokens should be normalized."""
-        assert _normalize_tool_name("done<|channel|>commentary") == "done"
-        assert _normalize_tool_name("recall<|endoftext|>") == "recall"
-        assert _normalize_tool_name("search_observations<|im_end|>extra") == "search_observations"
+        assert _normalize_tool_name("call=functions.search_mental_models") == "search_mental_models"
 
     def test_is_done_tool(self):
         """Test _is_done_tool helper."""
@@ -180,14 +100,9 @@ class TestToolNameNormalization:
         assert _is_done_tool("call=done") is True
         assert _is_done_tool("call=functions.done") is True
 
-        # With malformed special tokens
-        assert _is_done_tool("done<|channel|>commentary") is True
-        assert _is_done_tool("done<|endoftext|>") is True
-
         # Not done
         assert _is_done_tool("functions.recall") is False
         assert _is_done_tool("call=functions.recall") is False
-        assert _is_done_tool("recall<|channel|>done") is False
 
 
 class TestReflectAgentMocked:
@@ -208,8 +123,8 @@ class TestReflectAgentMocked:
     def mock_functions(self):
         """Create mock search/recall functions."""
         return {
+            "search_reflections_fn": AsyncMock(return_value={"reflections": []}),
             "search_mental_models_fn": AsyncMock(return_value={"mental_models": []}),
-            "search_observations_fn": AsyncMock(return_value={"observations": []}),
             "recall_fn": AsyncMock(return_value={"memories": [{"id": "mem-1", "content": "test memory"}]}),
             "expand_fn": AsyncMock(return_value={"memories": []}),
         }

hindsight-api/tests/test_reflections.py

@@ -1,4 +1,4 @@
-"""Tests for mental models (formerly reflections), observations, and learnings functionality."""
+"""Tests for reflections, mental models, and learnings functionality."""
 
 import uuid
 
@@ -21,22 +21,22 @@ async def api_client(memory):
 @pytest.fixture
 def test_bank_id():
     """Provide a unique bank ID for this test run."""
-    return f"test_mental_models_{uuid.uuid4().hex[:8]}"
+    return f"test_reflections_{uuid.uuid4().hex[:8]}"
 
 
-class TestMentalModelsCRUD:
-    """Test mental models CRUD operations via memory engine."""
+class TestReflectionsCRUD:
+    """Test reflections 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]}"
+    async def test_create_and_get_reflection(self, memory: MemoryEngine, request_context):
+        """Test creating and retrieving a reflection."""
+        bank_id = f"test-reflection-{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(
+        # Create a reflection
+        reflection = await memory.create_reflection(
             bank_id=bank_id,
             name="Team Preferences",
             source_query="What are the team's communication preferences?",
@@ -45,45 +45,45 @@ class TestMentalModelsCRUD:
             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
+        assert reflection["name"] == "Team Preferences"
+        assert reflection["source_query"] == "What are the team's communication preferences?"
+        assert reflection["content"] == "The team prefers async communication via Slack"
+        assert reflection["tags"] == ["team"]
+        assert "id" in reflection
 
-        # Get the mental model
-        fetched = await memory.get_mental_model(
+        # Get the reflection
+        fetched = await memory.get_reflection(
             bank_id=bank_id,
-            mental_model_id=mental_model["id"],
+            reflection_id=reflection["id"],
             request_context=request_context,
         )
 
-        assert fetched["id"] == mental_model["id"]
+        assert fetched["id"] == reflection["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]}"
+    async def test_list_reflections(self, memory: MemoryEngine, request_context):
+        """Test listing reflections with filters."""
+        bank_id = f"test-reflection-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(
+        # Create multiple reflections
+        await memory.create_reflection(
             bank_id=bank_id,
-            name="Mental Model 1",
+            name="Reflection 1",
             source_query="Query 1",
             content="Content 1",
             tags=["tag1"],
             request_context=request_context,
         )
-        await memory.create_mental_model(
+        await memory.create_reflection(
             bank_id=bank_id,
-            name="Mental Model 2",
+            name="Reflection 2",
             source_query="Query 2",
             content="Content 2",
             tags=["tag2"],
@@ -91,33 +91,33 @@ class TestMentalModelsCRUD:
         )
 
         # List all
-        all_mental_models = await memory.list_mental_models(
+        all_reflections = await memory.list_reflections(
             bank_id=bank_id,
             request_context=request_context,
         )
-        assert len(all_mental_models) == 2
+        assert len(all_reflections) == 2
 
         # List with tag filter
-        tag1_mental_models = await memory.list_mental_models(
+        tag1_reflections = await memory.list_reflections(
             bank_id=bank_id,
             tags=["tag1"],
             request_context=request_context,
         )
-        assert len(tag1_mental_models) == 1
+        assert len(tag1_reflections) == 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]}"
+    async def test_update_reflection(self, memory: MemoryEngine, request_context):
+        """Test updating a reflection."""
+        bank_id = f"test-reflection-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(
+        # Create a reflection
+        reflection = await memory.create_reflection(
             bank_id=bank_id,
             name="Original Name",
             source_query="Original Query",
@@ -125,10 +125,10 @@ class TestMentalModelsCRUD:
             request_context=request_context,
         )
 
-        # Update the mental model
-        updated = await memory.update_mental_model(
+        # Update the reflection
+        updated = await memory.update_reflection(
             bank_id=bank_id,
-            mental_model_id=mental_model["id"],
+            reflection_id=reflection["id"],
             name="Updated Name",
             content="Updated Content",
             request_context=request_context,
@@ -141,15 +141,15 @@ class TestMentalModelsCRUD:
         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]}"
+    async def test_delete_reflection(self, memory: MemoryEngine, request_context):
+        """Test deleting a reflection."""
+        bank_id = f"test-reflection-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(
+        # Create a reflection
+        reflection = await memory.create_reflection(
             bank_id=bank_id,
             name="To Delete",
             source_query="Query",
@@ -157,17 +157,17 @@ class TestMentalModelsCRUD:
             request_context=request_context,
         )
 
-        # Delete the mental model
-        await memory.delete_mental_model(
+        # Delete the reflection
+        await memory.delete_reflection(
             bank_id=bank_id,
-            mental_model_id=mental_model["id"],
+            reflection_id=reflection["id"],
             request_context=request_context,
         )
 
         # Verify deletion - should return None
-        fetched = await memory.get_mental_model(
+        fetched = await memory.get_reflection(
             bank_id=bank_id,
-            mental_model_id=mental_model["id"],
+            reflection_id=reflection["id"],
             request_context=request_context,
         )
         assert fetched is None
@@ -176,45 +176,45 @@ class TestMentalModelsCRUD:
         await memory.delete_bank(bank_id, request_context=request_context)
 
 
-class TestObservationsAPI:
-    """Test observations API endpoints.
+class TestMentalModelsAPI:
+    """Test mental models 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
+    NOTE: Mental models are now stored in memory_units with fact_type='mental_model'
+    and accessed via recall with fact_type=["mental_model"]. The old /mental-models
     endpoint was removed. These tests are skipped.
     """
 
-    @pytest.mark.skip(reason="Observations endpoint removed - use recall with fact_type=['observation']")
+    @pytest.mark.skip(reason="Mental models endpoint removed - use recall with fact_type=['mental_model']")
     @pytest.mark.asyncio
-    async def test_list_observations_empty(self, api_client, test_bank_id):
-        """Test listing observations when none exist."""
+    async def test_list_mental_models_empty(self, api_client, test_bank_id):
+        """Test listing mental models when none exist."""
         pass
 
-    @pytest.mark.skip(reason="Observations endpoint removed - use recall with fact_type=['observation']")
+    @pytest.mark.skip(reason="Mental models endpoint removed - use recall with fact_type=['mental_model']")
     @pytest.mark.asyncio
-    async def test_get_observation_not_found(self, api_client, test_bank_id):
-        """Test getting a non-existent observation."""
+    async def test_get_mental_model_not_found(self, api_client, test_bank_id):
+        """Test getting a non-existent mental model."""
         pass
 
 
-class TestMentalModelsAPI:
-    """Test mental models API endpoints."""
+class TestReflectionsAPI:
+    """Test reflections API endpoints."""
 
     @pytest.mark.asyncio
-    async def test_mental_models_api_crud(self, api_client, test_bank_id):
+    async def test_reflections_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)
+        # Create a reflection (async operation)
         response = await api_client.post(
-            f"/v1/default/banks/{test_bank_id}/mental-models",
+            f"/v1/default/banks/{test_bank_id}/reflections",
             json={
-                "name": "API Test Mental Model",
+                "name": "API Test Reflection",
                 "source_query": "What is the API test about?",
-                "content": "This is an API test mental model",
+                "content": "This is an API test reflection",
                 "tags": ["api-test"],
             },
         )
@@ -232,72 +232,44 @@ class TestMentalModelsAPI:
                     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")
+        # List reflections to get the created reflection
+        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/reflections")
         assert response.status_code == 200
-        mental_models = response.json()["items"]
-        assert len(mental_models) >= 1
+        reflections = response.json()["items"]
+        assert len(reflections) >= 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"]
+        # Find our reflection
+        reflection = next((r for r in reflections if r["name"] == "API Test Reflection"), None)
+        assert reflection is not None, f"Reflection not found. Items: {reflections}"
+        reflection_id = reflection["id"]
 
-        # Get the mental model
-        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/mental-models/{mental_model_id}")
+        # Get the reflection
+        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/reflections/{reflection_id}")
         assert response.status_code == 200
-        assert response.json()["name"] == "API Test Mental Model"
+        assert response.json()["name"] == "API Test Reflection"
 
-        # Update the mental model
+        # Update the reflection
         response = await api_client.patch(
-            f"/v1/default/banks/{test_bank_id}/mental-models/{mental_model_id}",
-            json={"name": "Updated API Test Mental Model"},
+            f"/v1/default/banks/{test_bank_id}/reflections/{reflection_id}",
+            json={"name": "Updated API Test Reflection"},
         )
         assert response.status_code == 200
-        assert response.json()["name"] == "Updated API Test Mental Model"
+        assert response.json()["name"] == "Updated API Test Reflection"
 
-        # Delete the mental model
-        response = await api_client.delete(f"/v1/default/banks/{test_bank_id}/mental-models/{mental_model_id}")
+        # Delete the reflection
+        response = await api_client.delete(f"/v1/default/banks/{test_bank_id}/reflections/{reflection_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}")
+        response = await api_client.get(f"/v1/default/banks/{test_bank_id}/reflections/{reflection_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}")
+class TestRecallWithMentalModelsAndReflections:
+    """Test recall integration with mental models and reflections."""
 
     @pytest.mark.asyncio
     async def test_recall_includes_mental_models(self, api_client, test_bank_id):
@@ -305,9 +277,37 @@ class TestRecallWithObservationsAndMentalModels:
         # Create bank first via profile endpoint
         await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")
 
-        # Create a mental model first
+        # Note: Mental models are auto-created via consolidation, not manually
+        # This test just verifies the include parameter works
+
+        # Recall with mental models included
         response = await api_client.post(
-            f"/v1/default/banks/{test_bank_id}/mental-models",
+            f"/v1/default/banks/{test_bank_id}/memories/recall",
+            json={
+                "query": "What is machine learning?",
+                "include": {
+                    "mental_models": {"max_results": 5},
+                },
+            },
+        )
+        assert response.status_code == 200
+        result = response.json()
+
+        # Should have mental_models field in response (may be empty)
+        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_includes_reflections(self, api_client, test_bank_id):
+        """Test that recall can include reflections in the response."""
+        # Create bank first via profile endpoint
+        await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")
+
+        # Create a reflection first
+        response = await api_client.post(
+            f"/v1/default/banks/{test_bank_id}/reflections",
             json={
                 "name": "AI Overview",
                 "source_query": "What is AI?",
@@ -317,32 +317,32 @@ class TestRecallWithObservationsAndMentalModels:
         )
         assert response.status_code == 200
 
-        # Recall with mental models included
+        # Recall with reflections 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},
+                    "reflections": {"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
+        # Should have reflections in response (may be empty if embedding not generated yet)
+        assert "reflections" in result or result.get("reflections") 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."""
+    async def test_recall_without_mental_models_by_default(self, api_client, test_bank_id):
+        """Test that recall does not include mental models by default."""
         # Create bank first via profile endpoint
         await api_client.get(f"/v1/default/banks/{test_bank_id}/profile")
 
-        # Recall without specifying observations
+        # Recall without specifying mental models
         response = await api_client.post(
             f"/v1/default/banks/{test_bank_id}/memories/recall",
             json={
@@ -352,97 +352,8 @@ class TestRecallWithObservationsAndMentalModels:
         assert response.status_code == 200
         result = response.json()
 
-        # Observations should not be in response
-        assert result.get("observations") is None
+        # Mental models should not be in response
+        assert result.get("mental_models") 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

@@ -2082,117 +2082,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_sql_schema_safety.py

@@ -22,7 +22,7 @@ TABLES = [
     "chunks",
     "async_operations",
     "directives",
-    "mental_models",
+    "reflections",
 ]
 
 # 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_tei_cross_encoder.py

@@ -527,7 +527,6 @@ class TestRemoteTEICrossEncoderConfig:
         """Test creating encoder from environment variables."""
         import os
 
-        from hindsight_api.config import clear_config_cache
         from hindsight_api.engine.cross_encoder import create_cross_encoder_from_env
 
         with patch.dict(
@@ -539,7 +538,6 @@ class TestRemoteTEICrossEncoderConfig:
                 "HINDSIGHT_API_RERANKER_TEI_MAX_CONCURRENT": "16",
             },
         ):
-            clear_config_cache()  # Clear cache to pick up patched env vars
             encoder = create_cross_encoder_from_env()
 
             assert isinstance(encoder, RemoteTEICrossEncoder)
@@ -547,8 +545,6 @@ class TestRemoteTEICrossEncoderConfig:
             assert encoder.batch_size == 256
             assert encoder.max_concurrent == 16
 
-        clear_config_cache()  # Clear cache after test
-
 
 # ============================================================================
 # TEI Reranker Performance Benchmark Tests

hindsight-api/tests/test_vertexai_provider.py

@@ -1,303 +0,0 @@
-"""
-Test Vertex AI provider integration including token refresh and API calls.
-"""
-
-import asyncio
-import os
-from unittest.mock import MagicMock, Mock, patch
-
-import pytest
-
-# Skip all tests if google-auth not available
-pytest.importorskip("google.auth")
-
-
-@pytest.mark.asyncio
-async def test_token_refresher_initialization():
-    """Test token refresher initialization with mocked credentials."""
-    from hindsight_api.engine.vertexai_token_refresher import VertexAITokenRefresher
-
-    # Mock credentials
-    mock_credentials = MagicMock()
-    mock_credentials.token = "test-token-123"
-    mock_credentials.expiry = None
-
-    with patch("google.auth.transport.requests.Request"):
-        refresher = VertexAITokenRefresher(mock_credentials, "test-project", "us-central1")
-
-        # Verify token was fetched
-        assert refresher.get_token() == "test-token-123"
-
-        # Verify base URL is correctly formatted
-        expected_url = (
-            "https://us-central1-aiplatform.googleapis.com/v1beta1/"
-            "projects/test-project/locations/us-central1/endpoints/openapi"
-        )
-        assert refresher.get_base_url() == expected_url
-
-
-@pytest.mark.asyncio
-async def test_token_refresher_background_refresh():
-    """Test that background refresh task starts and stops correctly."""
-    from hindsight_api.engine.vertexai_token_refresher import VertexAITokenRefresher
-
-    # Mock credentials
-    mock_credentials = MagicMock()
-    mock_credentials.token = "test-token-123"
-    mock_credentials.expiry = None
-
-    with patch("google.auth.transport.requests.Request"):
-        refresher = VertexAITokenRefresher(mock_credentials, "test-project", "us-central1")
-
-        # Start refresh task
-        refresher.start_refresh_task()
-        assert refresher._refresh_task is not None
-        assert not refresher._refresh_task.done()
-
-        # Stop refresh task
-        await refresher.stop()
-        assert refresher._refresh_task.done()
-
-
-@pytest.mark.asyncio
-async def test_token_refresher_thread_safety():
-    """Test that token access is thread-safe."""
-    from hindsight_api.engine.vertexai_token_refresher import VertexAITokenRefresher
-
-    # Mock credentials
-    mock_credentials = MagicMock()
-    mock_credentials.token = "test-token-123"
-    mock_credentials.expiry = None
-
-    with patch("google.auth.transport.requests.Request"):
-        refresher = VertexAITokenRefresher(mock_credentials, "test-project", "us-central1")
-
-        # Access token from multiple tasks concurrently
-        async def get_token_task():
-            return refresher.get_token()
-
-        results = await asyncio.gather(*[get_token_task() for _ in range(10)])
-
-        # All should return the same token
-        assert all(token == "test-token-123" for token in results)
-
-
-@pytest.mark.asyncio
-async def test_token_refresher_no_token_error():
-    """Test that getting token without refresh raises error."""
-    from hindsight_api.engine.vertexai_token_refresher import VertexAITokenRefresher
-
-    # Mock credentials that fail to refresh
-    mock_credentials = MagicMock()
-    mock_credentials.token = None
-
-    with patch("google.auth.transport.requests.Request") as mock_request:
-        mock_request.side_effect = Exception("Refresh failed")
-
-        with pytest.raises(Exception, match="Refresh failed"):
-            VertexAITokenRefresher(mock_credentials, "test-project", "us-central1")
-
-
-def test_llm_wrapper_vertexai_missing_dependency():
-    """Test error when google-auth is not available."""
-    from hindsight_api.engine import llm_wrapper
-
-    # Temporarily disable Vertex AI availability
-    original_available = llm_wrapper.VERTEXAI_AVAILABLE
-    try:
-        llm_wrapper.VERTEXAI_AVAILABLE = False
-
-        with pytest.raises(ValueError, match="google-auth"):
-            from hindsight_api.engine.llm_wrapper import LLMProvider
-
-            LLMProvider(
-                provider="vertexai",
-                api_key="",
-                base_url="",
-                model="google/gemini-2.0-flash-001",
-            )
-    finally:
-        llm_wrapper.VERTEXAI_AVAILABLE = original_available
-
-
-def test_llm_wrapper_vertexai_missing_project_id():
-    """Test error when project ID is not configured."""
-    with patch.dict(os.environ, {"HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID": ""}, clear=False):
-        # Clear config cache to reload from env
-        from hindsight_api.config import clear_config_cache
-
-        clear_config_cache()
-
-        with pytest.raises(ValueError, match="HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID"):
-            from hindsight_api.engine.llm_wrapper import LLMProvider
-
-            LLMProvider(
-                provider="vertexai",
-                api_key="",
-                base_url="",
-                model="google/gemini-2.0-flash-001",
-            )
-
-        # Restore config cache
-        clear_config_cache()
-
-
-@pytest.mark.asyncio
-async def test_llm_wrapper_vertexai_adc_auth():
-    """Test Vertex AI with ADC authentication (mocked)."""
-    from hindsight_api.engine.llm_wrapper import LLMProvider
-
-    mock_credentials = MagicMock()
-    mock_credentials.token = "test-token-adc"
-    mock_credentials.expiry = None
-
-    with patch.dict(
-        os.environ,
-        {"HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID": "test-project"},
-        clear=False,
-    ):
-        # Clear config cache to reload from env
-        from hindsight_api.config import clear_config_cache
-
-        clear_config_cache()
-
-        with patch("google.auth.default", return_value=(mock_credentials, "test-project")):
-            with patch("google.auth.transport.requests.Request"):
-                provider = LLMProvider(
-                    provider="vertexai",
-                    api_key="",
-                    base_url="",
-                    model="google/gemini-2.0-flash-001",
-                )
-
-                assert provider.provider == "vertexai"
-                assert provider._vertexai_refresher is not None
-                assert "aiplatform.googleapis.com" in provider.base_url
-
-                # Cleanup
-                await provider.cleanup()
-
-        # Restore config cache
-        clear_config_cache()
-
-
-@pytest.mark.asyncio
-async def test_llm_wrapper_vertexai_sa_auth():
-    """Test Vertex AI with service account authentication (mocked)."""
-    from hindsight_api.engine.llm_wrapper import LLMProvider
-    import google.auth.exceptions
-
-    mock_credentials = MagicMock()
-    mock_credentials.token = "test-token-sa"
-    mock_credentials.expiry = None
-
-    with patch.dict(
-        os.environ,
-        {
-            "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID": "test-project",
-            "HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY": "/path/to/key.json",
-        },
-        clear=False,
-    ):
-        # Clear config cache to reload from env
-        from hindsight_api.config import clear_config_cache
-
-        clear_config_cache()
-
-        # Mock ADC failure, SA success
-        with patch(
-            "google.auth.default",
-            side_effect=google.auth.exceptions.DefaultCredentialsError("ADC not available"),
-        ):
-            with patch(
-                "google.oauth2.service_account.Credentials.from_service_account_file",
-                return_value=mock_credentials,
-            ):
-                with patch("google.auth.transport.requests.Request"):
-                    provider = LLMProvider(
-                        provider="vertexai",
-                        api_key="",
-                        base_url="",
-                        model="google/gemini-2.0-flash-001",
-                    )
-
-                    assert provider.provider == "vertexai"
-                    assert provider._vertexai_refresher is not None
-
-                    # Cleanup
-                    await provider.cleanup()
-
-        # Restore config cache
-        clear_config_cache()
-
-
-@pytest.mark.asyncio
-async def test_llm_wrapper_vertexai_auth_failure():
-    """Test Vertex AI with both ADC and SA auth failing."""
-    import google.auth.exceptions
-
-    with patch.dict(
-        os.environ,
-        {"HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID": "test-project"},
-        clear=False,
-    ):
-        # Clear config cache to reload from env
-        from hindsight_api.config import clear_config_cache
-
-        clear_config_cache()
-
-        # Mock both ADC and SA failures
-        with patch(
-            "google.auth.default",
-            side_effect=google.auth.exceptions.DefaultCredentialsError("ADC failed"),
-        ):
-            with pytest.raises(ValueError, match="authentication failed"):
-                from hindsight_api.engine.llm_wrapper import LLMProvider
-
-                LLMProvider(
-                    provider="vertexai",
-                    api_key="",
-                    base_url="",
-                    model="google/gemini-2.0-flash-001",
-                )
-
-        # Restore config cache
-        clear_config_cache()
-
-
-@pytest.mark.asyncio
-@pytest.mark.skipif(
-    not os.getenv("HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID"),
-    reason="Vertex AI integration tests require HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID",
-)
-async def test_vertexai_integration_actual_api():
-    """
-    Integration test with actual Vertex AI API.
-
-    Requires:
-    - HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID
-    - ADC or HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY
-    """
-    from hindsight_api.engine.llm_wrapper import LLMProvider
-
-    provider = LLMProvider(
-        provider="vertexai",
-        api_key="",
-        base_url="",
-        model="google/gemini-2.0-flash-001",
-    )
-
-    try:
-        # Simple test call
-        response = await provider.call(
-            messages=[{"role": "user", "content": "Say 'ok' and nothing else"}],
-            max_completion_tokens=10,
-        )
-
-        assert response is not None
-        assert isinstance(response, str)
-        assert len(response) > 0
-
-    finally:
-        # Cleanup
-        await provider.cleanup()

hindsight-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "hindsight-cli"
-version = "0.4.2"
+version = "0.3.0"
 edition = "2021"
 authors = ["Hindsight Team"]
 description = "A beautiful CLI for Hindsight - semantic memory system"

hindsight-cli/src/api.rs

@@ -437,57 +437,57 @@ impl ApiClient {
         })
     }
 
-    // --- Mental Model Methods ---
+    // --- Reflection Methods ---
 
-    pub fn list_mental_models(&self, bank_id: &str, _verbose: bool) -> Result<types::MentalModelListResponse> {
+    pub fn list_reflections(&self, bank_id: &str, _verbose: bool) -> Result<types::ReflectionListResponse> {
         self.runtime.block_on(async {
-            let response = self.client.list_mental_models(bank_id, None, None, None, None, None).await?;
+            let response = self.client.list_reflections(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> {
+    pub fn get_reflection(&self, bank_id: &str, reflection_id: &str, _verbose: bool) -> Result<types::ReflectionResponse> {
         self.runtime.block_on(async {
-            let response = self.client.get_mental_model(bank_id, mental_model_id, None).await?;
+            let response = self.client.get_reflection(bank_id, reflection_id, None).await?;
             Ok(response.into_inner())
         })
     }
 
-    pub fn create_mental_model(
+    pub fn create_reflection(
         &self,
         bank_id: &str,
-        request: &types::CreateMentalModelRequest,
+        request: &types::CreateReflectionRequest,
         _verbose: bool,
-    ) -> Result<types::CreateMentalModelResponse> {
+    ) -> Result<types::CreateReflectionResponse> {
         self.runtime.block_on(async {
-            let response = self.client.create_mental_model(bank_id, None, request).await?;
+            let response = self.client.create_reflection(bank_id, None, request).await?;
             Ok(response.into_inner())
         })
     }
 
-    pub fn update_mental_model(
+    pub fn update_reflection(
         &self,
         bank_id: &str,
-        mental_model_id: &str,
-        request: &types::UpdateMentalModelRequest,
+        reflection_id: &str,
+        request: &types::UpdateReflectionRequest,
         _verbose: bool,
-    ) -> Result<types::MentalModelResponse> {
+    ) -> Result<types::ReflectionResponse> {
         self.runtime.block_on(async {
-            let response = self.client.update_mental_model(bank_id, mental_model_id, None, request).await?;
+            let response = self.client.update_reflection(bank_id, reflection_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> {
+    pub fn delete_reflection(&self, bank_id: &str, reflection_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?;
+            let response = self.client.delete_reflection(bank_id, reflection_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> {
+    pub fn refresh_reflection(&self, bank_id: &str, reflection_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?;
+            let response = self.client.refresh_reflection(bank_id, reflection_id, None).await?;
             Ok(response.into_inner())
         })
     }
@@ -539,31 +539,6 @@ impl ApiClient {
             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/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/mod.rs

@@ -7,5 +7,5 @@ pub mod explore;
 pub mod health;
 pub mod memory;
 pub mod operation;
-pub mod mental_model;
+pub mod reflection;
 pub mod tag;

hindsight-cli/src/commands/reflection.rs

@@ -1,4 +1,4 @@
-//! Mental model commands for managing user-curated summaries.
+//! Reflection commands for managing user-curated summaries.
 
 use anyhow::Result;
 
@@ -8,7 +8,7 @@ use crate::ui;
 
 use hindsight_client::types;
 
-/// List mental models for a bank
+/// List reflections for a bank
 pub fn list(
     client: &ApiClient,
     bank_id: &str,
@@ -16,12 +16,12 @@ pub fn list(
     output_format: OutputFormat,
 ) -> Result<()> {
     let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching mental models..."))
+        Some(ui::create_spinner("Fetching reflections..."))
     } else {
         None
     };
 
-    let response = client.list_mental_models(bank_id, verbose);
+    let response = client.list_reflections(bank_id, verbose);
 
     if let Some(mut sp) = spinner {
         sp.finish();
@@ -30,21 +30,21 @@ pub fn list(
     match response {
         Ok(result) => {
             if output_format == OutputFormat::Pretty {
-                ui::print_section_header(&format!("Mental Models: {}", bank_id));
+                ui::print_section_header(&format!("Reflections: {}", bank_id));
 
                 if result.items.is_empty() {
-                    println!("  {}", ui::dim("No mental models found."));
+                    println!("  {}", ui::dim("No reflections found."));
                 } else {
-                    for mental_model in &result.items {
+                    for reflection in &result.items {
                         println!(
                             "  {} {}",
-                            ui::gradient_start(&mental_model.id),
-                            mental_model.name
+                            ui::gradient_start(&reflection.id),
+                            reflection.name
                         );
 
                         // Show content preview
-                        let preview: String = mental_model.content.chars().take(80).collect();
-                        let ellipsis = if mental_model.content.len() > 80 { "..." } else { "" };
+                        let preview: String = reflection.content.chars().take(80).collect();
+                        let ellipsis = if reflection.content.len() > 80 { "..." } else { "" };
                         println!("    {}{}", ui::dim(&preview), ellipsis);
 
                         println!();
@@ -59,32 +59,32 @@ pub fn list(
     }
 }
 
-/// Get a specific mental model
+/// Get a specific reflection
 pub fn get(
     client: &ApiClient,
     bank_id: &str,
-    mental_model_id: &str,
+    reflection_id: &str,
     verbose: bool,
     output_format: OutputFormat,
 ) -> Result<()> {
     let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Fetching mental model..."))
+        Some(ui::create_spinner("Fetching reflection..."))
     } else {
         None
     };
 
-    let response = client.get_mental_model(bank_id, mental_model_id, verbose);
+    let response = client.get_reflection(bank_id, reflection_id, verbose);
 
     if let Some(mut sp) = spinner {
         sp.finish();
     }
 
     match response {
-        Ok(mental_model) => {
+        Ok(reflection) => {
             if output_format == OutputFormat::Pretty {
-                print_mental_model_detail(&mental_model);
+                print_reflection_detail(&reflection);
             } else {
-                output::print_output(&mental_model, output_format)?;
+                output::print_output(&reflection, output_format)?;
             }
             Ok(())
         }
@@ -92,7 +92,7 @@ pub fn get(
     }
 }
 
-/// Create a new mental model
+/// Create a new reflection
 pub fn create(
     client: &ApiClient,
     bank_id: &str,
@@ -102,20 +102,19 @@ pub fn create(
     output_format: OutputFormat,
 ) -> Result<()> {
     let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Creating mental model..."))
+        Some(ui::create_spinner("Creating reflection..."))
     } else {
         None
     };
 
-    let request = types::CreateMentalModelRequest {
+    let request = types::CreateReflectionRequest {
         name: name.to_string(),
         source_query: source_query.to_string(),
         max_tokens: 2048,
         tags: vec![],
-        trigger: None,
     };
 
-    let response = client.create_mental_model(bank_id, &request, verbose);
+    let response = client.create_reflection(bank_id, &request, verbose);
 
     if let Some(mut sp) = spinner {
         sp.finish();
@@ -124,7 +123,7 @@ pub fn create(
     match response {
         Ok(result) => {
             if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Mental model created, operation_id: {}", result.operation_id));
+                ui::print_success(&format!("Reflection created, operation_id: {}", result.operation_id));
             } else {
                 output::print_output(&result, output_format)?;
             }
@@ -134,11 +133,11 @@ pub fn create(
     }
 }
 
-/// Update a mental model
+/// Update a reflection
 pub fn update(
     client: &ApiClient,
     bank_id: &str,
-    mental_model_id: &str,
+    reflection_id: &str,
     name: Option<String>,
     verbose: bool,
     output_format: OutputFormat,
@@ -148,33 +147,27 @@ pub fn update(
     }
 
     let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Updating mental model..."))
+        Some(ui::create_spinner("Updating reflection..."))
     } else {
         None
     };
 
-    let request = types::UpdateMentalModelRequest {
-        name,
-        source_query: None,
-        max_tokens: None,
-        tags: None,
-        trigger: None,
-    };
+    let request = types::UpdateReflectionRequest { name };
 
-    let response = client.update_mental_model(bank_id, mental_model_id, &request, verbose);
+    let response = client.update_reflection(bank_id, reflection_id, &request, verbose);
 
     if let Some(mut sp) = spinner {
         sp.finish();
     }
 
     match response {
-        Ok(mental_model) => {
+        Ok(reflection) => {
             if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Mental model '{}' updated successfully", mental_model_id));
+                ui::print_success(&format!("Reflection '{}' updated successfully", reflection_id));
                 println!();
-                print_mental_model_detail(&mental_model);
+                print_reflection_detail(&reflection);
             } else {
-                output::print_output(&mental_model, output_format)?;
+                output::print_output(&reflection, output_format)?;
             }
             Ok(())
         }
@@ -182,11 +175,11 @@ pub fn update(
     }
 }
 
-/// Delete a mental model
+/// Delete a reflection
 pub fn delete(
     client: &ApiClient,
     bank_id: &str,
-    mental_model_id: &str,
+    reflection_id: &str,
     yes: bool,
     verbose: bool,
     output_format: OutputFormat,
@@ -194,8 +187,8 @@ pub fn delete(
     // Confirmation prompt unless -y flag is used
     if !yes && output_format == OutputFormat::Pretty {
         let message = format!(
-            "Are you sure you want to delete mental model '{}'? This cannot be undone.",
-            mental_model_id
+            "Are you sure you want to delete reflection '{}'? This cannot be undone.",
+            reflection_id
         );
 
         let confirmed = ui::prompt_confirmation(&message)?;
@@ -207,12 +200,12 @@ pub fn delete(
     }
 
     let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Deleting mental model..."))
+        Some(ui::create_spinner("Deleting reflection..."))
     } else {
         None
     };
 
-    let response = client.delete_mental_model(bank_id, mental_model_id, verbose);
+    let response = client.delete_reflection(bank_id, reflection_id, verbose);
 
     if let Some(mut sp) = spinner {
         sp.finish();
@@ -221,7 +214,7 @@ pub fn delete(
     match response {
         Ok(_) => {
             if output_format == OutputFormat::Pretty {
-                ui::print_success(&format!("Mental model '{}' deleted successfully", mental_model_id));
+                ui::print_success(&format!("Reflection '{}' deleted successfully", reflection_id));
             } else {
                 println!("{{\"success\": true}}");
             }
@@ -231,21 +224,21 @@ pub fn delete(
     }
 }
 
-/// Refresh a mental model
+/// Refresh a reflection
 pub fn refresh(
     client: &ApiClient,
     bank_id: &str,
-    mental_model_id: &str,
+    reflection_id: &str,
     verbose: bool,
     output_format: OutputFormat,
 ) -> Result<()> {
     let spinner = if output_format == OutputFormat::Pretty {
-        Some(ui::create_spinner("Submitting mental model refresh..."))
+        Some(ui::create_spinner("Submitting reflection refresh..."))
     } else {
         None
     };
 
-    let response = client.refresh_mental_model(bank_id, mental_model_id, verbose);
+    let response = client.refresh_reflection(bank_id, reflection_id, verbose);
 
     if let Some(mut sp) = spinner {
         sp.finish();
@@ -255,7 +248,7 @@ pub fn refresh(
         Ok(operation) => {
             if output_format == OutputFormat::Pretty {
                 ui::print_success(&format!(
-                    "Mental model refresh submitted. Operation ID: {}",
+                    "Reflection refresh submitted. Operation ID: {}",
                     operation.operation_id
                 ));
                 println!("  {} {}", ui::dim("Status:"), operation.status);
@@ -270,16 +263,16 @@ 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);
+// Helper function to print reflection details
+fn print_reflection_detail(reflection: &types::ReflectionResponse) {
+    ui::print_section_header(&reflection.name);
 
-    println!("  {} {}", ui::dim("ID:"), ui::gradient_start(&mental_model.id));
-    println!("  {} {}", ui::dim("Source Query:"), &mental_model.source_query);
+    println!("  {} {}", ui::dim("ID:"), ui::gradient_start(&reflection.id));
+    println!("  {} {}", ui::dim("Source Query:"), &reflection.source_query);
 
     println!();
     println!("{}", ui::gradient_text("─── Content ───"));
     println!();
-    println!("{}", &mental_model.content);
+    println!("{}", &reflection.content);
     println!();
 }

hindsight-cli/src/main.rs

@@ -95,9 +95,9 @@ enum Commands {
     #[command(subcommand)]
     Operation(OperationCommands),
 
-    /// Manage mental models (user-curated summaries)
+    /// Manage reflections (user-curated summaries)
     #[command(subcommand)]
-    MentalModel(MentalModelCommands),
+    Reflection(ReflectionCommands),
 
     /// Manage directives (behavioral rules)
     #[command(subcommand)]
@@ -109,9 +109,6 @@ enum Commands {
     /// 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 +252,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)]
@@ -558,67 +539,67 @@ enum ChunkCommands {
 }
 
 #[derive(Subcommand)]
-enum MentalModelCommands {
-    /// List mental models for a bank
+enum ReflectionCommands {
+    /// List reflections for a bank
     List {
         /// Bank ID
         bank_id: String,
     },
 
-    /// Get a specific mental model
+    /// Get a specific reflection
     Get {
         /// Bank ID
         bank_id: String,
 
-        /// Mental model ID
-        mental_model_id: String,
+        /// Reflection ID
+        reflection_id: String,
     },
 
-    /// Create a new mental model
+    /// Create a new reflection
     Create {
         /// Bank ID
         bank_id: String,
 
-        /// Mental model name
+        /// Reflection name
         name: String,
 
-        /// Source query to generate the mental model from
+        /// Source query to generate the reflection from
         source_query: String,
     },
 
-    /// Update a mental model
+    /// Update a reflection
     Update {
         /// Bank ID
         bank_id: String,
 
-        /// Mental model ID
-        mental_model_id: String,
+        /// Reflection ID
+        reflection_id: String,
 
         /// New name
         #[arg(long)]
         name: Option<String>,
     },
 
-    /// Delete a mental model
+    /// Delete a reflection
     Delete {
         /// Bank ID
         bank_id: String,
 
-        /// Mental model ID
-        mental_model_id: String,
+        /// Reflection ID
+        reflection_id: String,
 
         /// Skip confirmation prompt
         #[arg(short = 'y', long)]
         yes: bool,
     },
 
-    /// Refresh a mental model (re-run the source query)
+    /// Refresh a reflection (re-run the source query)
     Refresh {
         /// Bank ID
         bank_id: String,
 
-        /// Mental model ID
-        mental_model_id: String,
+        /// Reflection ID
+        reflection_id: String,
     },
 }
 
@@ -725,10 +706,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 +734,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
@@ -843,25 +817,25 @@ fn run() -> Result<()> {
             }
         },
 
-        // Mental model commands
-        Commands::MentalModel(mm_cmd) => match mm_cmd {
-            MentalModelCommands::List { bank_id } => {
-                commands::mental_model::list(&client, &bank_id, verbose, output_format)
+        // Reflection commands
+        Commands::Reflection(ref_cmd) => match ref_cmd {
+            ReflectionCommands::List { bank_id } => {
+                commands::reflection::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)
+            ReflectionCommands::Get { bank_id, reflection_id } => {
+                commands::reflection::get(&client, &bank_id, &reflection_id, verbose, output_format)
             }
-            MentalModelCommands::Create { bank_id, name, source_query } => {
-                commands::mental_model::create(&client, &bank_id, &name, &source_query, verbose, output_format)
+            ReflectionCommands::Create { bank_id, name, source_query } => {
+                commands::reflection::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)
+            ReflectionCommands::Update { bank_id, reflection_id, name } => {
+                commands::reflection::update(&client, &bank_id, &reflection_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)
+            ReflectionCommands::Delete { bank_id, reflection_id, yes } => {
+                commands::reflection::delete(&client, &bank_id, &reflection_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)
+            ReflectionCommands::Refresh { bank_id, reflection_id } => {
+                commands::reflection::refresh(&client, &bank_id, &reflection_id, verbose, output_format)
             }
         },
 

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-cli/tests/integration_test.rs

@@ -1,125 +0,0 @@
-use std::process::Command;
-
-#[test]
-fn test_cli_help() {
-    let output = Command::new("cargo")
-        .args(["run", "--", "--help"])
-        .output()
-        .expect("Failed to execute command");
-
-    assert!(output.status.success());
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    assert!(stdout.contains("Hindsight CLI"));
-}
-
-#[test]
-fn test_cli_version() {
-    let output = Command::new("cargo")
-        .args(["run", "--", "--version"])
-        .output()
-        .expect("Failed to execute command");
-
-    assert!(output.status.success());
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    assert!(stdout.contains("hindsight"));
-}
-
-#[test]
-fn test_ui_command_without_config() {
-    // Test that the ui command handles missing config gracefully
-    // Create a temp home directory with no config
-    let temp_dir = std::env::temp_dir().join(format!("hindsight-test-ui-{}", std::process::id()));
-    std::fs::create_dir_all(&temp_dir).expect("Failed to create temp dir");
-
-    let output = Command::new("cargo")
-        .args(["run", "--", "ui"])
-        .env_remove("HINDSIGHT_API_URL")
-        .env_remove("HINDSIGHT_API_KEY")
-        .env("HOME", &temp_dir)
-        .output()
-        .expect("Failed to execute command");
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-
-    // Either it fails with a config error or it succeeds if there's a default config
-    // Just verify it doesn't crash unexpectedly
-    assert!(
-        !output.status.success()
-        || stdout.contains("Launching Hindsight Control Plane UI")
-        || stderr.contains("Configuration error")
-        || stderr.contains("HINDSIGHT_API_URL"),
-        "Unexpected output - stdout: {}, stderr: {}",
-        stdout,
-        stderr
-    );
-
-    // Cleanup
-    std::fs::remove_dir_all(&temp_dir).ok();
-}
-
-#[test]
-fn test_ui_command_with_config() {
-    // This test is skipped by default since it requires a running control plane
-    // and would block for a long time. The other tests cover the basic functionality.
-    // To run this test manually:
-    // 1. Build the control plane: cd hindsight-control-plane && npm run build
-    // 2. Run: cargo test test_ui_command_with_config -- --ignored
-
-    // Just verify that the ui command accepts the configuration
-    let temp_dir = std::env::temp_dir().join(format!("hindsight-test-ui-valid-{}", std::process::id()));
-    std::fs::create_dir_all(&temp_dir).expect("Failed to create temp dir");
-
-    // Write a minimal config
-    let config_dir = temp_dir.join(".config").join("hindsight");
-    std::fs::create_dir_all(&config_dir).expect("Failed to create config dir");
-    let config_file = config_dir.join("config");
-    std::fs::write(&config_file, "api_url=http://localhost:8888\napi_key=test-key\n")
-        .expect("Failed to write config");
-
-    let output = Command::new("cargo")
-        .args(["run", "--", "ui", "--help"])
-        .env("HOME", &temp_dir)
-        .output()
-        .expect("Failed to execute command");
-
-    // The --help should work regardless
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    assert!(stdout.contains("Hindsight CLI") || output.status.success());
-
-    // Cleanup
-    std::fs::remove_dir_all(&temp_dir).ok();
-}
-
-#[test]
-fn test_configure_command() {
-    // Test that configure command creates/updates config
-    let temp_dir = std::env::temp_dir().join(format!("hindsight-test-{}", std::process::id()));
-    std::fs::create_dir_all(&temp_dir).expect("Failed to create temp dir");
-
-    let output = Command::new("cargo")
-        .args([
-            "run",
-            "--",
-            "configure",
-            "--api-url",
-            "http://localhost:9999",
-            "--api-key",
-            "test-key-123"
-        ])
-        .env("HOME", &temp_dir)
-        .output()
-        .expect("Failed to execute command");
-
-    assert!(
-        output.status.success(),
-        "Configure command failed: {}",
-        String::from_utf8_lossy(&output.stderr)
-    );
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    assert!(stdout.contains("Configuration saved") || stdout.contains("success"));
-
-    // Cleanup
-    std::fs::remove_dir_all(&temp_dir).ok();
-}

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

@@ -5,9 +5,9 @@ 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
-hindsight_client_api/api/mental_models_api.py
 hindsight_client_api/api/monitoring_api.py
 hindsight_client_api/api/operations_api.py
+hindsight_client_api/api/reflections_api.py
 hindsight_client_api/api_client.py
 hindsight_client_api/api_response.py
 hindsight_client_api/configuration.py
@@ -28,8 +28,8 @@ 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/create_reflection_request.py
+hindsight_client_api/models/create_reflection_response.py
 hindsight_client_api/models/delete_document_response.py
 hindsight_client_api/models/delete_response.py
 hindsight_client_api/models/directive_list_response.py
@@ -51,9 +51,6 @@ 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_list_response.py
-hindsight_client_api/models/mental_model_response.py
-hindsight_client_api/models/mental_model_trigger.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,6 +66,8 @@ 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/reflection_list_response.py
+hindsight_client_api/models/reflection_response.py
 hindsight_client_api/models/retain_request.py
 hindsight_client_api/models/retain_response.py
 hindsight_client_api/models/tag_item.py
@@ -77,7 +75,7 @@ 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/update_reflection_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-clients/python/hindsight_client/hindsight_client.py

@@ -10,7 +10,7 @@ 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 banks_api, memory_api
 from hindsight_client_api.models import (
     memory_item,
     recall_request,
@@ -78,8 +78,6 @@ class Hindsight:
             self._api_client.set_default_header("Authorization", f"Bearer {api_key}")
         self._memory_api = memory_api.MemoryApi(self._api_client)
         self._banks_api = banks_api.BanksApi(self._api_client)
-        self._mental_models_api = mental_models_api.MentalModelsApi(self._api_client)
-        self._directives_api = directives_api.DirectivesApi(self._api_client)
 
     def __enter__(self):
         """Context manager entry."""
@@ -536,253 +534,3 @@ class Hindsight:
         )
 
         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

@@ -7,7 +7,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.
@@ -22,9 +22,9 @@ 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
-from hindsight_client_api.api.mental_models_api import MentalModelsApi
 from hindsight_client_api.api.monitoring_api import MonitoringApi
 from hindsight_client_api.api.operations_api import OperationsApi
+from hindsight_client_api.api.reflections_api import ReflectionsApi
 
 # import ApiClient
 from hindsight_client_api.api_response import ApiResponse
@@ -53,8 +53,8 @@ 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.create_reflection_request import CreateReflectionRequest
+from hindsight_client_api.models.create_reflection_response import CreateReflectionResponse
 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
@@ -76,9 +76,6 @@ 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_list_response import MentalModelListResponse
-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.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,6 +91,8 @@ 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.reflection_list_response import ReflectionListResponse
+from hindsight_client_api.models.reflection_response import ReflectionResponse
 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
@@ -102,7 +100,7 @@ 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.update_reflection_request import UpdateReflectionRequest
 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

@@ -6,7 +6,7 @@ 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
-from hindsight_client_api.api.mental_models_api import MentalModelsApi
 from hindsight_client_api.api.monitoring_api import MonitoringApi
 from hindsight_client_api.api.operations_api import OperationsApi
+from hindsight_client_api.api.reflections_api import ReflectionsApi
 

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.
@@ -356,7 +356,7 @@ class BanksApi:
 
 
     @validate_call
-    async def clear_observations(
+    async def clear_mental_models(
         self,
         bank_id: StrictStr,
         authorization: Optional[StrictStr] = None,
@@ -373,9 +373,9 @@ class BanksApi:
         _headers: Optional[Dict[StrictStr, Any]] = None,
         _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
     ) -> DeleteResponse:
-        """Clear all observations
+        """Clear all mental models
 
-        Delete all observations for a memory bank. This is useful for resetting the consolidated knowledge.
+        Delete all mental models for a memory bank. This is useful for resetting the consolidated knowledge.
 
         :param bank_id: (required)
         :type bank_id: str
@@ -403,7 +403,7 @@ class BanksApi:
         :return: Returns the result object.
         """ # noqa: E501
 
-        _param = self._clear_observations_serialize(
+        _param = self._clear_mental_models_serialize(
             bank_id=bank_id,
             authorization=authorization,
             _request_auth=_request_auth,
@@ -428,7 +428,7 @@ class BanksApi:
 
 
     @validate_call
-    async def clear_observations_with_http_info(
+    async def clear_mental_models_with_http_info(
         self,
         bank_id: StrictStr,
         authorization: Optional[StrictStr] = None,
@@ -445,9 +445,9 @@ class BanksApi:
         _headers: Optional[Dict[StrictStr, Any]] = None,
         _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
     ) -> ApiResponse[DeleteResponse]:
-        """Clear all observations
+        """Clear all mental models
 
-        Delete all observations for a memory bank. This is useful for resetting the consolidated knowledge.
+        Delete all mental models for a memory bank. This is useful for resetting the consolidated knowledge.
 
         :param bank_id: (required)
         :type bank_id: str
@@ -475,7 +475,7 @@ class BanksApi:
         :return: Returns the result object.
         """ # noqa: E501
 
-        _param = self._clear_observations_serialize(
+        _param = self._clear_mental_models_serialize(
             bank_id=bank_id,
             authorization=authorization,
             _request_auth=_request_auth,
@@ -500,7 +500,7 @@ class BanksApi:
 
 
     @validate_call
-    async def clear_observations_without_preload_content(
+    async def clear_mental_models_without_preload_content(
         self,
         bank_id: StrictStr,
         authorization: Optional[StrictStr] = None,
@@ -517,9 +517,9 @@ class BanksApi:
         _headers: Optional[Dict[StrictStr, Any]] = None,
         _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
     ) -> RESTResponseType:
-        """Clear all observations
+        """Clear all mental models
 
-        Delete all observations for a memory bank. This is useful for resetting the consolidated knowledge.
+        Delete all mental models for a memory bank. This is useful for resetting the consolidated knowledge.
 
         :param bank_id: (required)
         :type bank_id: str
@@ -547,7 +547,7 @@ class BanksApi:
         :return: Returns the result object.
         """ # noqa: E501
 
-        _param = self._clear_observations_serialize(
+        _param = self._clear_mental_models_serialize(
             bank_id=bank_id,
             authorization=authorization,
             _request_auth=_request_auth,
@@ -567,7 +567,7 @@ class BanksApi:
         return response_data.response
 
 
-    def _clear_observations_serialize(
+    def _clear_mental_models_serialize(
         self,
         bank_id,
         authorization,
@@ -617,7 +617,7 @@ class BanksApi:
 
         return self.api_client.param_serialize(
             method='DELETE',
-            resource_path='/v1/default/banks/{bank_id}/observations',
+            resource_path='/v1/default/banks/{bank_id}/mental-models',
             path_params=_path_params,
             query_params=_query_params,
             header_params=_header_params,
@@ -2056,7 +2056,7 @@ class BanksApi:
     ) -> ConsolidationResponse:
         """Trigger consolidation
 
-        Run memory consolidation to create/update observations from recent memories.
+        Run memory consolidation to create/update mental models from recent memories.
 
         :param bank_id: (required)
         :type bank_id: str
@@ -2128,7 +2128,7 @@ class BanksApi:
     ) -> ApiResponse[ConsolidationResponse]:
         """Trigger consolidation
 
-        Run memory consolidation to create/update observations from recent memories.
+        Run memory consolidation to create/update mental models from recent memories.
 
         :param bank_id: (required)
         :type bank_id: str
@@ -2200,7 +2200,7 @@ class BanksApi:
     ) -> RESTResponseType:
         """Trigger consolidation
 
-        Run memory consolidation to create/update observations from recent memories.
+        Run memory consolidation to create/update mental models from recent memories.
 
         :param bank_id: (required)
         :type bank_id: str

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

hindsight-clients/python/hindsight_client_api/api_client.py

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

hindsight-clients/python/hindsight_client_api/configuration.py

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.
@@ -489,7 +489,7 @@ class Configuration:
         return "Python SDK Debug Report:\n"\
                "OS: {env}\n"\
                "Python Version: {pyversion}\n"\
-               "Version of the API: 0.4.2\n"\
+               "Version of the API: 0.1.0\n"\
                "SDK Package Version: 0.0.7".\
                format(env=sys.platform, pyversion=sys.version)
 

hindsight-clients/python/hindsight_client_api/exceptions.py

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -6,7 +6,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.
@@ -29,8 +29,8 @@ 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.create_reflection_request import CreateReflectionRequest
+from hindsight_client_api.models.create_reflection_response import CreateReflectionResponse
 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
@@ -52,9 +52,6 @@ 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_list_response import MentalModelListResponse
-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.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 +59,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,6 +67,8 @@ 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.reflection_list_response import ReflectionListResponse
+from hindsight_client_api.models.reflection_response import ReflectionResponse
 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
@@ -78,7 +76,7 @@ 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.update_reflection_request import UpdateReflectionRequest
 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/add_background_request.py

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.
@@ -37,9 +37,9 @@ class BankStatsResponse(BaseModel):
     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"]
+    pending_consolidation: Optional[StrictInt] = Field(default=0, description="Number of memories not yet processed into mental models")
+    total_mental_models: Optional[StrictInt] = Field(default=0, description="Total number of mental models")
+    __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_mental_models"]
 
     model_config = ConfigDict(
         populate_by_name=True,
@@ -109,7 +109,7 @@ class BankStatsResponse(BaseModel):
             "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
+            "total_mental_models": obj.get("total_mental_models") if obj.get("total_mental_models") is not None else 0
         })
         return _obj
 

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.
@@ -20,20 +20,18 @@ 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 typing import Optional, Set
 from typing_extensions import Self
 
-class CreateMentalModelRequest(BaseModel):
+class CreateReflectionRequest(BaseModel):
     """
-    Request model for creating a mental model.
+    Request model for creating a reflection.
     """ # noqa: E501
-    name: StrictStr = Field(description="Human-readable name for the mental model")
+    name: StrictStr = Field(description="Human-readable name for the reflection")
     source_query: StrictStr = Field(description="The query to run to generate content")
     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", "source_query", "tags", "max_tokens"]
 
     model_config = ConfigDict(
         populate_by_name=True,
@@ -53,7 +51,7 @@ class CreateMentalModelRequest(BaseModel):
 
     @classmethod
     def from_json(cls, json_str: str) -> Optional[Self]:
-        """Create an instance of CreateMentalModelRequest from a JSON string"""
+        """Create an instance of CreateReflectionRequest from a JSON string"""
         return cls.from_dict(json.loads(json_str))
 
     def to_dict(self) -> Dict[str, Any]:
@@ -74,14 +72,11 @@ 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()
         return _dict
 
     @classmethod
     def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
-        """Create an instance of CreateMentalModelRequest from a dict"""
+        """Create an instance of CreateReflectionRequest from a dict"""
         if obj is None:
             return None
 
@@ -92,8 +87,7 @@ class CreateMentalModelRequest(BaseModel):
             "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
+            "max_tokens": obj.get("max_tokens") if obj.get("max_tokens") is not None else 2048
         })
         return _obj
 

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.
@@ -22,9 +22,9 @@ from typing import Any, ClassVar, Dict, List
 from typing import Optional, Set
 from typing_extensions import Self
 
-class CreateMentalModelResponse(BaseModel):
+class CreateReflectionResponse(BaseModel):
     """
-    Response model for mental model creation.
+    Response model for reflection creation.
     """ # noqa: E501
     operation_id: StrictStr = Field(description="Operation ID to track progress")
     __properties: ClassVar[List[str]] = ["operation_id"]
@@ -47,7 +47,7 @@ class CreateMentalModelResponse(BaseModel):
 
     @classmethod
     def from_json(cls, json_str: str) -> Optional[Self]:
-        """Create an instance of CreateMentalModelResponse from a JSON string"""
+        """Create an instance of CreateReflectionResponse from a JSON string"""
         return cls.from_dict(json.loads(json_str))
 
     def to_dict(self) -> Dict[str, Any]:
@@ -72,7 +72,7 @@ class CreateMentalModelResponse(BaseModel):
 
     @classmethod
     def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
-        """Create an instance of CreateMentalModelResponse from a dict"""
+        """Create an instance of CreateReflectionResponse from a dict"""
         if obj is None:
             return None
 

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.

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

@@ -5,7 +5,7 @@
 
     HTTP API for Hindsight
 
-    The version of the OpenAPI document: 0.4.2
+    The version of the OpenAPI document: 0.1.0
     Generated by OpenAPI Generator (https://openapi-generator.tech)
 
     Do not edit the class manually.