feat: add real-time timing breakdown logging for consolidation

- Log timing breakdown after each batch (every 50 memories by default) - Log timing breakdown in progress logs (every 10 memories) - Shows recall, llm, embedding, db_write times incrementally - Includes avg time per memory for quick diagnosis - Helps diagnose performance issues in production without waiting for job completion Example output (every 10 memories): [CONSOLIDATION] bank=xyz progress: 10/39303 memories processed | recall=2.09s, llm=11.03s, embedding=0.48s, db_write=0.02s Example output (per batch): [CONSOLIDATION] bank=xyz batch 1/50 memories: recall=7.3s, llm=57.5s, embedding=2.0s, db_write=0.09s | avg=1.3s/memory
Release v0.4.1
2026-01-29 17:37:01 +01:00 · 2026-01-29 11:25:28 +01:00 · 2026-01-29 11:24:15 +01:00 · 2026-01-29 08:46:21 +01:00 · 2026-01-29 08:40:01 +01:00 · 2026-01-28 19:26:12 -07:00
187 changed files with 10405 additions and 485 deletions
@@ -26,6 +26,7 @@ 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)
@@ -45,9 +45,12 @@ 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.md
+# Changelog is now tracked in hindsight-docs/src/pages/changelog.md
+# CHANGELOG.md
@@ -1,6 +1,6 @@
 <div align="center">

-![Hindsight Banner](./hindsight-docs/static/img/banner.svg)
+![Hindsight Banner](./hindsight-docs/static/img/hindsight-github-banner.png)

 [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,55 +17,31 @@

 ## What is Hindsight?

-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™ 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 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.

- **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.
+<video src="https://github.com/user-attachments/assets/923b798d-3581-4897-bb62-9cfa5a931682" controls></video>

-## 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.
-
---
+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.

 ## Memory Performance & Accuracy

-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:
+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:

 ![Overview](./hindsight-docs/static/img/hindsight-bench.jpg)

-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.
+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.

-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.
+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)

-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

@@ -148,8 +124,45 @@ 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.
@@ -208,7 +221,7 @@ The final output is trimmed as needed to fit within the token limit.

 ### Reflect

-The reflect operation is used to perform a more thorough analysis of existing memories. This allows the agent to form new connections between memories which are then persisted as opinions and/or observations. When building agents, the reflect operation is a key capability to enable the agent to learn from its experiences. 
+The reflect operation is used to perform a more thorough analysis of existing memories. This allows the agent to form new connections between memories and build a more thorough understanding of its world.

 For example, the `reflect` operation can be used to support use cases such as:

@@ -2,8 +2,8 @@ apiVersion: v2
 name: hindsight
 description: Hindsight helm chart
 type: application
-version: 0.3.0
-appVersion: "0.3.0"
+version: 0.4.1
+appVersion: "0.4.1"
 keywords:
  - ai
  - memory
@@ -46,4 +46,4 @@ __all__ = [
    "RemoteTEICrossEncoder",
    "LLMConfig",
 ]
-__version__ = "0.1.0"
+__version__ = "0.4.1"
@@ -1323,7 +1323,7 @@ class VersionResponse(BaseModel):
    model_config = ConfigDict(
        json_schema_extra={
            "example": {
-                "api_version": "1.0.0",
+                "api_version": "0.4.0",
                "features": {
                    "observations": False,
                    "mcp": True,
@@ -1567,11 +1567,12 @@ 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="1.0.0",
+            api_version=__version__,
            features=FeaturesInfo(
                observations=config.enable_observations,
                mcp=config.mcp_enabled,
@@ -20,6 +20,7 @@ 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"
@@ -46,6 +47,7 @@ ENV_CONSOLIDATION_LLM_BASE_URL = "HINDSIGHT_API_CONSOLIDATION_LLM_BASE_URL"

 ENV_EMBEDDINGS_PROVIDER = "HINDSIGHT_API_EMBEDDINGS_PROVIDER"
 ENV_EMBEDDINGS_LOCAL_MODEL = "HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL"
+ENV_EMBEDDINGS_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"
@@ -65,6 +67,7 @@ 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"
@@ -98,6 +101,7 @@ ENV_RETAIN_OBSERVATIONS_ASYNC = "HINDSIGHT_API_RETAIN_OBSERVATIONS_ASYNC"
 # Observations settings (consolidated knowledge from facts)
 ENV_ENABLE_OBSERVATIONS = "HINDSIGHT_API_ENABLE_OBSERVATIONS"
 ENV_CONSOLIDATION_BATCH_SIZE = "HINDSIGHT_API_CONSOLIDATION_BATCH_SIZE"
+ENV_CONSOLIDATION_MAX_TOKENS = "HINDSIGHT_API_CONSOLIDATION_MAX_TOKENS"

 # Optimization flags
 ENV_SKIP_LLM_VERIFICATION = "HINDSIGHT_API_SKIP_LLM_VERIFICATION"
@@ -125,6 +129,7 @@ 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
@@ -132,11 +137,13 @@ DEFAULT_LLM_TIMEOUT = 120.0  # seconds

 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
@@ -177,6 +184,7 @@ DEFAULT_RETAIN_OBSERVATIONS_ASYNC = False  # Run observation generation async (a
 # Observations defaults (consolidated knowledge from facts)
 DEFAULT_ENABLE_OBSERVATIONS = True  # Observations enabled by default
 DEFAULT_CONSOLIDATION_BATCH_SIZE = 50  # Memories to load per batch (internal memory optimization)
+DEFAULT_CONSOLIDATION_MAX_TOKENS = 1024  # Max tokens for recall when finding related observations

 # Database migrations
 DEFAULT_RUN_MIGRATIONS_ON_STARTUP = True
@@ -270,6 +278,7 @@ class HindsightConfig:

    # Database
    database_url: str
+    database_schema: str

    # LLM (default, used as fallback for per-operation config)
    llm_provider: str
@@ -298,6 +307,7 @@ class HindsightConfig:
    # 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
@@ -305,6 +315,8 @@ 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
@@ -336,6 +348,7 @@ class HindsightConfig:
    # Observations settings (consolidated knowledge from facts)
    enable_observations: bool
    consolidation_batch_size: int
+    consolidation_max_tokens: int

    # Optimization flags
    skip_llm_verification: bool
@@ -367,6 +380,7 @@ 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),
@@ -390,12 +404,23 @@ class HindsightConfig:
            # 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(
@@ -444,6 +469,9 @@ class HindsightConfig:
            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
@@ -515,7 +543,7 @@ class HindsightConfig:

    def log_config(self) -> None:
        """Log the current configuration (without sensitive values)."""
-        logger.info(f"Database: {self.database_url}")
+        logger.info(f"Database: {self.database_url} (schema: {self.database_schema})")
        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
@@ -144,10 +144,14 @@ async def run_consolidation_job(
    }

    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()
@@ -217,19 +221,44 @@ async def run_consolidation_job(
            elif action == "skipped":
                stats["skipped"] += 1

-            # Log progress periodically
+            # Log progress periodically with timing breakdown
            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"
+                    f"{stats['memories_processed']}/{total_count} memories processed{timing_str}"
                )

+                # 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 -> "
@@ -639,28 +668,27 @@ async def _find_related_observations(
    request_context: "RequestContext",
 ) -> list[dict[str, Any]]:
    """
-    Find observations related to the given query using the full recall system.
+    Find observations related to the given query using optimized recall.

    IMPORTANT: We do NOT filter by tags here. Consolidation needs to see ALL
    potentially related observations regardless of scope, so the LLM can
    decide on tag routing (same scope update vs cross-scope create).

-    This leverages:
-    - Semantic search (embedding similarity)
-    - BM25 text search (keyword matching)
-    - Entity-based retrieval (shared entities)
-    - Graph traversal (connected via entity links)
+    Uses max_tokens to naturally limit observations (no artificial count limit).
+    Includes source memories with dates for LLM context.

    Returns:
-        List of related observations with their tags for LLM tag routing
+        List of related observations with their tags, source memories, and dates
    """
-    # Use recall to find related observations
-    # NO tags parameter - we want ALL observations regardless of scope
-    # Use low max_tokens since we only need observations, not memories
+    # 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()
    recall_result = await memory_engine.recall_async(
        bank_id=bank_id,
        query=query,
-        max_tokens=5000,  # Token budget for observations
+        max_tokens=config.consolidation_max_tokens,  # Token budget for observations (configurable)
        fact_type=["observation"],  # Only retrieve observations
        request_context=request_context,
        _quiet=True,  # Suppress logging
@@ -668,43 +696,82 @@ async def _find_related_observations(
    )

    # If no observations returned, return empty list
-    # When fact_type=["observation"], results come back in `results` field
    if not recall_result.results:
        return []

-    # Trust recall's relevance filtering - fetch full data for each observation
+    # 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}
    results = []
+
    for obs in recall_result.results:
-        # Fetch full observation data from DB to get history, source_memory_ids, tags
-        row = await conn.fetchrow(
-            f"""
-            SELECT id, text, proof_count, history, tags, source_memory_ids, created_at, updated_at
-            FROM {fq_table("memory_units")}
-            WHERE id = $1 AND bank_id = $2 AND fact_type = 'observation'
-            """,
-            uuid.UUID(obs.id),
-            bank_id,
-        )
+        obs_id = uuid.UUID(obs.id)
+        if obs_id not in id_to_row:
+            continue

-        if row:
-            history = row["history"]
-            if isinstance(history, str):
-                history = json.loads(history)
-            elif history is None:
-                history = []
+        row = id_to_row[obs_id]
+        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
-                }
+        # 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"],
+            }
+        )
+
    return results


@@ -732,14 +799,43 @@ async def _consolidate_with_llm(
        - {"action": "create", "text": "...", "reason": "..."}
        - [] if fact is purely ephemeral (no durable knowledge)
    """
-    # Format observations WITH their tags (or "None" if empty)
+    # Format observations as JSON with source memories and dates
    if observations:
-        observations_text = "\n".join(
-            f'- ID: {obs["id"]}, Tags: {json.dumps(obs["tags"])}, Text: "{obs["text"]}" (proof_count: {obs["proof_count"]})'
-            for obs in observations
-        )
+        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)
    else:
-        observations_text = "None (this is a new topic - create if fact contains durable knowledge)"
+        observations_text = "[]"

    # Only include mission section if mission is set and not the default
    mission_section = ""
@@ -47,23 +47,31 @@ CONSOLIDATION_USER_PROMPT = """Analyze this new fact and consolidate into knowle
 {mission_section}
 NEW FACT: {fact_text}

-EXISTING OBSERVATIONS:
+EXISTING OBSERVATIONS (JSON array with source memories and dates):
 {observations_text}

-Instructions:
-1. First, extract the DURABLE KNOWLEDGE from the fact (not ephemeral state like "user is at X")
-2. Then compare with existing observations:
-   - If an observation covers the same topic: UPDATE it with the new knowledge
-   - If no observation covers the topic: CREATE a new one
+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

-Output JSON array of actions (ALWAYS an array, even for single action):
+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 []
+
+Output JSON array of actions:
 [
-  {{"action": "update", "learning_id": "uuid", "text": "updated durable knowledge", "reason": "..."}},
+  {{"action": "update", "learning_id": "uuid-from-observations", "text": "updated knowledge", "reason": "..."}},
  {{"action": "create", "text": "new durable knowledge", "reason": "..."}}
 ]

-If NO consolidation is needed (fact is purely ephemeral with no durable knowledge):
-[]
-
-If no observations exist and fact contains durable knowledge:
-[{{"action": "create", "text": "durable knowledge text", "reason": "new topic"}}]"""
+Return [] if fact contains no durable knowledge."""
@@ -20,6 +20,7 @@ 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,
@@ -33,6 +34,7 @@ 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,
@@ -99,7 +101,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):
+    def __init__(self, model_name: str | None = None, max_concurrent: int = 4, force_cpu: bool = False):
        """
        Initialize local SentenceTransformers cross-encoder.

@@ -108,8 +110,11 @@ 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

@@ -139,13 +144,23 @@ class LocalSTCrossEncoder(CrossEncoderModel):
        # after loading, which conflicts with accelerate's device_map handling.
        import torch

-        # 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:
+        # 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)")
+        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}")

        self._model = CrossEncoder(
            self.model_name,
@@ -163,11 +178,108 @@ class LocalSTCrossEncoder(CrossEncoderModel):
        else:
            logger.info("Reranker: local provider initialized (using existing executor)")

+    def _is_xpc_error(self, error: Exception) -> bool:
+        """
+        Check if an error is an XPC connection error (macOS daemon issue).
+
+        On macOS, long-running daemons can lose XPC connections to system services
+        when the process is idle for extended periods.
+        """
+        error_str = str(error).lower()
+        return "xpc_error_connection_invalid" in error_str or "xpc error" in error_str
+
+    def _reinitialize_model_sync(self) -> None:
+        """
+        Clear and reinitialize the cross-encoder model synchronously.
+
+        This is used to recover from XPC errors on macOS where the
+        PyTorch/MPS backend loses its connection to system services.
+        """
+        logger.warning(f"Reinitializing reranker model {self.model_name} due to backend error")
+
+        # Clear existing model
+        self._model = None
+
+        # Force garbage collection to free resources
+        import gc
+
+        import torch
+
+        gc.collect()
+
+        # If using CUDA/MPS, clear the cache
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+        elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+            try:
+                torch.mps.empty_cache()
+            except AttributeError:
+                pass  # Method might not exist in all PyTorch versions
+
+        # Reinitialize the model
+        try:
+            from sentence_transformers import CrossEncoder
+        except ImportError:
+            raise ImportError(
+                "sentence-transformers is required for LocalSTCrossEncoder. "
+                "Install it with: pip install sentence-transformers"
+            )
+
+        # Determine device based on hardware availability
+        if self.force_cpu:
+            device = "cpu"
+        else:
+            # Wrap in try-except to gracefully handle any device detection issues
+            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 during reinit, falling back to CPU: {e}")
+
+        self._model = CrossEncoder(
+            self.model_name,
+            device=device,
+            model_kwargs={"low_cpu_mem_usage": False},
+        )
+
+        logger.info("Reranker: local provider reinitialized successfully")
+
+    def _predict_with_recovery(self, pairs: list[tuple[str, str]]) -> list[float]:
+        """
+        Predict with automatic recovery from XPC errors.
+
+        This runs synchronously in the thread pool.
+        """
+        max_retries = 1
+        for attempt in range(max_retries + 1):
+            try:
+                scores = self._model.predict(pairs, show_progress_bar=False)
+                return scores.tolist() if hasattr(scores, "tolist") else list(scores)
+            except Exception as e:
+                # Check if this is an XPC error (macOS daemon issue)
+                if self._is_xpc_error(e) and attempt < max_retries:
+                    logger.warning(f"XPC error detected in reranker (attempt {attempt + 1}): {e}")
+                    try:
+                        self._reinitialize_model_sync()
+                        logger.info("Reranker reinitialized successfully, retrying prediction")
+                        continue
+                    except Exception as reinit_error:
+                        logger.error(f"Failed to reinitialize reranker: {reinit_error}")
+                        raise Exception(f"Failed to recover from XPC error: {str(e)}")
+                else:
+                    # Not an XPC error or out of retries
+                    raise
+
    async def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
        """
        Score query-document pairs for relevance.

        Uses a dedicated thread pool with limited workers to prevent CPU thrashing.
+        Automatically recovers from XPC errors on macOS by reinitializing the model.

        Args:
            pairs: List of (query, document) tuples to score
@@ -180,11 +292,11 @@ class LocalSTCrossEncoder(CrossEncoderModel):

        # Use dedicated executor - limited workers naturally limits concurrency
        loop = asyncio.get_event_loop()
-        scores = await loop.run_in_executor(
+        return await loop.run_in_executor(
            LocalSTCrossEncoder._executor,
-            lambda: self._model.predict(pairs, show_progress_bar=False),
+            self._predict_with_recovery,
+            pairs,
        )
-        return scores.tolist() if hasattr(scores, "tolist") else list(scores)


 class RemoteTEICrossEncoder(CrossEncoderModel):
@@ -783,29 +895,33 @@ class LiteLLMCrossEncoder(CrossEncoderModel):

 def create_cross_encoder_from_env() -> CrossEncoderModel:
    """
-    Create a CrossEncoderModel instance based on environment variables.
+    Create a CrossEncoderModel instance based on configuration.

-    See hindsight_api.config for environment variable names and defaults.
+    Reads configuration via get_config() to ensure consistency across the codebase.

    Returns:
        Configured CrossEncoderModel instance
    """
-    provider = os.environ.get(ENV_RERANKER_PROVIDER, DEFAULT_RERANKER_PROVIDER).lower()
+    from ..config import get_config
+
+    config = get_config()
+    provider = config.reranker_provider.lower()

    if provider == "tei":
-        url = os.environ.get(ENV_RERANKER_TEI_URL)
+        url = config.reranker_tei_url
        if not url:
            raise ValueError(f"{ENV_RERANKER_TEI_URL} is required when {ENV_RERANKER_PROVIDER} is 'tei'")
-        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)
+        return RemoteTEICrossEncoder(
+            base_url=url,
+            batch_size=config.reranker_tei_batch_size,
+            max_concurrent=config.reranker_tei_max_concurrent,
+        )
    elif provider == "local":
-        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=config.reranker_local_model,
+            max_concurrent=config.reranker_local_max_concurrent,
+            force_cpu=config.reranker_local_force_cpu,
        )
-        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:
@@ -18,6 +18,7 @@ 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,
@@ -26,6 +27,7 @@ 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,
@@ -92,15 +94,18 @@ class LocalSTEmbeddings(Embeddings):
    The embedding dimension is auto-detected from the model.
    """

-    def __init__(self, model_name: str | None = None):
+    def __init__(self, model_name: str | None = None, force_cpu: bool = False):
        """
        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

@@ -134,13 +139,23 @@ class LocalSTEmbeddings(Embeddings):
        # which can cause issues when accelerate is installed but no GPU is available.
        import torch

-        # 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:
+        # 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")
+        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}")

        self._model = SentenceTransformer(
            self.model_name,
@@ -151,10 +166,82 @@ class LocalSTEmbeddings(Embeddings):
        self._dimension = self._model.get_sentence_embedding_dimension()
        logger.info(f"Embeddings: local provider initialized (dim: {self._dimension})")

+    def _is_xpc_error(self, error: Exception) -> bool:
+        """
+        Check if an error is an XPC connection error (macOS daemon issue).
+
+        On macOS, long-running daemons can lose XPC connections to system services
+        when the process is idle for extended periods.
+        """
+        error_str = str(error).lower()
+        return "xpc_error_connection_invalid" in error_str or "xpc error" in error_str
+
+    def _reinitialize_model_sync(self) -> None:
+        """
+        Clear and reinitialize the embedding model synchronously.
+
+        This is used to recover from XPC errors on macOS where the
+        PyTorch/MPS backend loses its connection to system services.
+        """
+        logger.warning(f"Reinitializing embedding model {self.model_name} due to backend error")
+
+        # Clear existing model
+        self._model = None
+
+        # Force garbage collection to free resources
+        import gc
+
+        import torch
+
+        gc.collect()
+
+        # If using CUDA/MPS, clear the cache
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+        elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+            try:
+                torch.mps.empty_cache()
+            except AttributeError:
+                pass  # Method might not exist in all PyTorch versions
+
+        # Reinitialize the model (inline version of initialize() but synchronous)
+        try:
+            from sentence_transformers import SentenceTransformer
+        except ImportError:
+            raise ImportError(
+                "sentence-transformers is required for LocalSTEmbeddings. "
+                "Install it with: pip install sentence-transformers"
+            )
+
+        # Determine device based on hardware availability
+        if self.force_cpu:
+            device = "cpu"
+        else:
+            # Wrap in try-except to gracefully handle any device detection issues
+            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 during reinit, falling back to CPU: {e}")
+
+        self._model = SentenceTransformer(
+            self.model_name,
+            device=device,
+            model_kwargs={"low_cpu_mem_usage": False},
+        )
+
+        logger.info("Embeddings: local provider reinitialized successfully")
+
    def encode(self, texts: list[str]) -> list[list[float]]:
        """
        Generate embeddings for a list of texts.

+        Automatically recovers from XPC errors on macOS by reinitializing the model.
+
        Args:
            texts: List of text strings to encode

@@ -163,8 +250,27 @@ 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]
+
+        # Try encoding with automatic recovery from XPC errors
+        max_retries = 1
+        for attempt in range(max_retries + 1):
+            try:
+                embeddings = self._model.encode(texts, convert_to_numpy=True, show_progress_bar=False)
+                return [emb.tolist() for emb in embeddings]
+            except Exception as e:
+                # Check if this is an XPC error (macOS daemon issue)
+                if self._is_xpc_error(e) and attempt < max_retries:
+                    logger.warning(f"XPC error detected in embedding generation (attempt {attempt + 1}): {e}")
+                    try:
+                        self._reinitialize_model_sync()
+                        logger.info("Model reinitialized successfully, retrying embedding generation")
+                        continue
+                    except Exception as reinit_error:
+                        logger.error(f"Failed to reinitialize model: {reinit_error}")
+                        raise Exception(f"Failed to recover from XPC error: {str(e)}")
+                else:
+                    # Not an XPC error or out of retries
+                    raise


 class RemoteTEIEmbeddings(Embeddings):
@@ -686,24 +792,28 @@ class LiteLLMEmbeddings(Embeddings):

 def create_embeddings_from_env() -> Embeddings:
    """
-    Create an Embeddings instance based on environment variables.
+    Create an Embeddings instance based on configuration.

-    See hindsight_api.config for environment variable names and defaults.
+    Reads configuration via get_config() to ensure consistency across the codebase.

    Returns:
        Configured Embeddings instance
    """
-    provider = os.environ.get(ENV_EMBEDDINGS_PROVIDER, DEFAULT_EMBEDDINGS_PROVIDER).lower()
+    from ..config import get_config
+
+    config = get_config()
+    provider = config.embeddings_provider.lower()

    if provider == "tei":
-        url = os.environ.get(ENV_EMBEDDINGS_TEI_URL)
+        url = config.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":
-        model = os.environ.get(ENV_EMBEDDINGS_LOCAL_MODEL)
-        model_name = model or DEFAULT_EMBEDDINGS_LOCAL_MODEL
-        return LocalSTEmbeddings(model_name=model_name)
+        return LocalSTEmbeddings(
+            model_name=config.embeddings_local_model,
+            force_cpu=config.embeddings_local_force_cpu,
+        )
    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)
@@ -23,12 +23,17 @@ from ..metrics import get_metrics_collector
 from .db_budget import budgeted_operation

 # Context variable for current schema (async-safe, per-task isolation)
-_current_schema: contextvars.ContextVar[str] = contextvars.ContextVar("current_schema", default="public")
+# Note: default is None, actual default comes from config via get_current_schema()
+_current_schema: contextvars.ContextVar[str | None] = contextvars.ContextVar("current_schema", default=None)


 def get_current_schema() -> str:
-    """Get the current schema from context (default: 'public')."""
-    return _current_schema.get()
+    """Get the current schema from context (falls back to config default)."""
+    schema = _current_schema.get()
+    if schema is None:
+        # Fall back to configured default schema
+        return get_config().database_schema
+    return schema


 def fq_table(table_name: str) -> str:
@@ -881,11 +886,12 @@ class MemoryEngine(MemoryEngineInterface):
            if not self.db_url:
                raise ValueError("Database URL is required for migrations")
            logger.info("Running database migrations...")
-            run_migrations(self.db_url)
+            # Use configured database schema for migrations (defaults to "public")
+            run_migrations(self.db_url, schema=get_config().database_schema)

            # Ensure embedding column dimension matches the model's dimension
            # This is done after migrations and after embeddings.initialize()
-            ensure_embedding_dimension(self.db_url, self.embeddings.dimension)
+            ensure_embedding_dimension(self.db_url, self.embeddings.dimension, schema=get_config().database_schema)

        logger.info(f"Connecting to PostgreSQL at {self.db_url}")

@@ -2764,7 +2770,7 @@ class MemoryEngine(MemoryEngineInterface):
            param_count += 1
            units = await conn.fetch(
                f"""
-                SELECT id, text, event_date, context, occurred_start, occurred_end, mentioned_at, document_id, chunk_id, fact_type, tags, created_at, proof_count
+                SELECT id, text, event_date, context, occurred_start, occurred_end, mentioned_at, document_id, chunk_id, fact_type, tags, created_at, proof_count, source_memory_ids
                FROM {fq_table("memory_units")}
                {where_clause}
                ORDER BY mentioned_at DESC NULLS LAST, event_date DESC
@@ -2777,7 +2783,18 @@ class MemoryEngine(MemoryEngineInterface):
            # Get links, filtering to only include links between units of the selected agent
            # Use DISTINCT ON with LEAST/GREATEST to deduplicate bidirectional links
            unit_ids = [row["id"] for row in units]
-            if unit_ids:
+            unit_id_set = set(unit_ids)
+
+            # Collect source memory IDs from observations
+            source_memory_ids = []
+            for unit in units:
+                if unit["source_memory_ids"]:
+                    source_memory_ids.extend(unit["source_memory_ids"])
+            source_memory_ids = list(set(source_memory_ids))  # Deduplicate
+
+            # Fetch links involving both visible units AND source memories
+            all_relevant_ids = unit_ids + source_memory_ids
+            if all_relevant_ids:
                links = await conn.fetch(
                    f"""
                    SELECT DISTINCT ON (LEAST(ml.from_unit_id, ml.to_unit_id), GREATEST(ml.from_unit_id, ml.to_unit_id), ml.link_type, COALESCE(ml.entity_id, '00000000-0000-0000-0000-000000000000'::uuid))
@@ -2788,14 +2805,69 @@ class MemoryEngine(MemoryEngineInterface):
                        e.canonical_name as entity_name
                    FROM {fq_table("memory_links")} ml
                    LEFT JOIN {fq_table("entities")} e ON ml.entity_id = e.id
-                    WHERE ml.from_unit_id = ANY($1::uuid[]) AND ml.to_unit_id = ANY($1::uuid[])
+                    WHERE ml.from_unit_id = ANY($1::uuid[]) OR ml.to_unit_id = ANY($1::uuid[])
                    ORDER BY LEAST(ml.from_unit_id, ml.to_unit_id), GREATEST(ml.from_unit_id, ml.to_unit_id), ml.link_type, COALESCE(ml.entity_id, '00000000-0000-0000-0000-000000000000'::uuid), ml.weight DESC
                """,
-                    unit_ids,
+                    all_relevant_ids,
                )
            else:
                links = []

+            # Copy links from source memories to observations
+            # Observations inherit links from their source memories via source_memory_ids
+            # Build a map from source_id to observation_ids
+            source_to_observations = {}
+            for unit in units:
+                if unit["source_memory_ids"]:
+                    for source_id in unit["source_memory_ids"]:
+                        if source_id not in source_to_observations:
+                            source_to_observations[source_id] = []
+                        source_to_observations[source_id].append(unit["id"])
+
+            copied_links = []
+            for link in links:
+                from_id = link["from_unit_id"]
+                to_id = link["to_unit_id"]
+
+                # Get observations that should inherit this link
+                from_observations = source_to_observations.get(from_id, [])
+                to_observations = source_to_observations.get(to_id, [])
+
+                # If from_id is a source memory, copy links to its observations
+                if from_observations:
+                    for obs_id in from_observations:
+                        # Only include if the target is visible
+                        if to_id in unit_id_set or to_observations:
+                            target = to_observations[0] if to_observations and to_id not in unit_id_set else to_id
+                            if target in unit_id_set:
+                                copied_links.append(
+                                    {
+                                        "from_unit_id": obs_id,
+                                        "to_unit_id": target,
+                                        "link_type": link["link_type"],
+                                        "weight": link["weight"],
+                                        "entity_name": link["entity_name"],
+                                    }
+                                )
+
+                # If to_id is a source memory, copy links to its observations
+                if to_observations and from_id in unit_id_set:
+                    for obs_id in to_observations:
+                        copied_links.append(
+                            {
+                                "from_unit_id": from_id,
+                                "to_unit_id": obs_id,
+                                "link_type": link["link_type"],
+                                "weight": link["weight"],
+                                "entity_name": link["entity_name"],
+                            }
+                        )
+
+            # Keep only direct links between visible nodes
+            direct_links = [
+                link for link in links if link["from_unit_id"] in unit_id_set and link["to_unit_id"] in unit_id_set
+            ]
+
            # Get entity information
            unit_entities = await conn.fetch(f"""
                SELECT ue.unit_id, e.canonical_name
@@ -2813,6 +2885,18 @@ class MemoryEngine(MemoryEngineInterface):
                entity_map[unit_id] = []
            entity_map[unit_id].append(entity_name)

+        # For observations, inherit entities from source memories
+        for unit in units:
+            if unit["source_memory_ids"] and unit["id"] not in entity_map:
+                # Collect entities from all source memories
+                source_entities = []
+                for source_id in unit["source_memory_ids"]:
+                    if source_id in entity_map:
+                        source_entities.extend(entity_map[source_id])
+                if source_entities:
+                    # Deduplicate while preserving order
+                    entity_map[unit["id"]] = list(dict.fromkeys(source_entities))
+
        # Build nodes
        nodes = []
        for row in units:
@@ -2846,14 +2930,15 @@ class MemoryEngine(MemoryEngineInterface):
                }
            )

-        # Build edges
+        # Build edges (combine direct links and copied links from sources)
        edges = []
-        for row in links:
+        all_links = direct_links + copied_links
+        for row in all_links:
            from_id = str(row["from_unit_id"])
            to_id = str(row["to_unit_id"])
            link_type = row["link_type"]
            weight = row["weight"]
-            entity_name = row["entity_name"]
+            entity_name = row.get("entity_name")

            # Color by link type
            if link_type == "temporal":
@@ -58,6 +58,7 @@ 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.)
    """
@@ -69,6 +70,11 @@ 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


@@ -69,7 +69,7 @@ async def tool_search_mental_models(
        next_param += 1

    if exclude_ids:
-        filters += f" AND id != ALL(${next_param}::uuid[])"
+        filters += f" AND id != ALL(${next_param}::text[])"
        params.append(exclude_ids)
        next_param += 1

@@ -155,7 +155,6 @@ class LinkExpansionRetriever(GraphRetriever):
                all_seeds.extend(temporal_seeds)

            if not all_seeds:
-                logger.info("[LinkExpansion] No seeds found, returning empty results")
                return [], timings

            seed_ids = list({s.id for s in all_seeds})
@@ -1,5 +1,6 @@
 """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

@@ -10,11 +11,13 @@ class ApiKeyTenantExtension(TenantExtension):

    This is a simple implementation that:
    1. Validates the API key matches HINDSIGHT_API_TENANT_API_KEY
-    2. Returns 'public' as the schema for all authenticated requests
+    2. Returns the configured schema (HINDSIGHT_API_DATABASE_SCHEMA, default 'public')
+       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.
@@ -27,11 +30,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 public schema context."""
+        """Validate API key and return configured schema context."""
        if context.api_key != self.expected_api_key:
            raise AuthenticationError("Invalid API key")
-        return TenantContext(schema_name="public")
+        return TenantContext(schema_name=get_config().database_schema)

    async def list_tenants(self) -> list[Tenant]:
-        """Return public schema for single-tenant setup."""
-        return [Tenant(schema="public")]
+        """Return configured schema for single-tenant setup."""
+        return [Tenant(schema=get_config().database_schema)]
@@ -140,6 +140,13 @@ def main():
        args.port = DEFAULT_DAEMON_PORT
        args.host = "127.0.0.1"  # Only bind to localhost for security

+        # Force CPU mode for daemon to avoid macOS MPS/XPC issues
+        # MPS (Metal Performance Shaders) has unstable XPC connections in background processes
+        # that can cause assertion failures and process crashes at the C++ level
+        # (which Python exception handlers cannot catch)
+        os.environ["HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU"] = "1"
+        os.environ["HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU"] = "1"
+
        # Check if another daemon is already running
        daemon_lock = DaemonLock()
        if not daemon_lock.acquire():
@@ -170,6 +177,7 @@ 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,
@@ -190,11 +198,14 @@ def main():
            consolidation_llm_base_url=config.consolidation_llm_base_url,
            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,
@@ -217,6 +228,7 @@ def main():
            retain_observations_async=config.retain_observations_async,
            enable_observations=config.enable_observations,
            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,
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "hindsight-api"
-version = "0.3.0"
+version = "0.4.1"
 description = "Hindsight: Agent Memory That Works Like Human Memory"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -1897,3 +1897,93 @@ class TestMentalModelRefreshAfterConsolidation:

        # Cleanup
        await memory.delete_bank(bank_id, request_context=request_context)
+
+    @pytest.mark.asyncio
+    async def test_graph_endpoint_observations_inherit_links_and_entities(
+        self, memory: MemoryEngine, request_context
+    ):
+        """Test that graph endpoint shows links and entities for observations filtered by type.
+
+        When filtering graph by type=observation:
+        - Observations should inherit links from their source memories
+        - Observations should show entities inherited from source memories
+        - Even when source memories are not visible, their links should be copied to observations
+        """
+        bank_id = f"test-graph-obs-{uuid.uuid4().hex[:8]}"
+
+        # Create the bank
+        await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)
+
+        # Retain content that will create world facts with shared entities
+        # This should create facts that are linked by shared entities
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Alice works at Google as a software engineer.",
+            request_context=request_context,
+        )
+
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Bob also works at Google in the sales department.",
+            request_context=request_context,
+        )
+
+        # Wait for consolidation to create observations
+        import asyncio
+
+        await asyncio.sleep(2)
+
+        # Get graph data filtered by observation type only
+        graph_data = await memory.get_graph_data(
+            bank_id=bank_id,
+            fact_type="observation",
+            limit=1000,
+            request_context=request_context,
+        )
+
+        # Should have observations
+        assert graph_data["total_units"] > 0, "Should have observations"
+        assert len(graph_data["nodes"]) > 0, "Should have observation nodes"
+
+        # Verify all nodes are observations
+        for row in graph_data["table_rows"]:
+            assert row["fact_type"] == "observation", f"All nodes should be observations, got {row['fact_type']}"
+
+        # Should have edges (inherited from source memories)
+        # Even though we're only showing observations, they should inherit links from their sources
+        assert len(graph_data["edges"]) > 0, (
+            "Observations should have edges inherited from source memories. "
+            f"Found {len(graph_data['edges'])} edges"
+        )
+
+        # Should have entities (inherited from source memories)
+        observations_with_entities = [
+            row for row in graph_data["table_rows"] if row["entities"] and row["entities"] != "None"
+        ]
+        assert len(observations_with_entities) > 0, (
+            "Observations should inherit entities from source memories. "
+            f"Found {len(observations_with_entities)} observations with entities"
+        )
+
+        # Verify entities contain expected values
+        all_entities = " ".join([row["entities"] for row in graph_data["table_rows"]])
+        assert "Alice" in all_entities or "Bob" in all_entities or "Google" in all_entities, (
+            f"Expected to find Alice, Bob, or Google in entities, got: {all_entities}"
+        )
+
+        # Verify edge types are valid
+        valid_link_types = {"semantic", "temporal", "entity"}
+        for edge in graph_data["edges"]:
+            link_type = edge["data"]["linkType"]
+            assert link_type in valid_link_types, f"Invalid link type: {link_type}"
+
+        # Verify all edges connect visible observation nodes
+        visible_node_ids = {row["id"] for row in graph_data["table_rows"]}
+        for edge in graph_data["edges"]:
+            source_id = edge["data"]["source"]
+            target_id = edge["data"]["target"]
+            assert source_id in visible_node_ids, f"Edge source {source_id[:8]} not in visible nodes"
+            assert target_id in visible_node_ids, f"Edge target {target_id[:8]} not in visible nodes"
+
+        # Cleanup
+        await memory.delete_bank(bank_id, request_context=request_context)
@@ -0,0 +1,148 @@
+"""
+Tests for XPC error recovery in LocalSTCrossEncoder.
+
+This tests the automatic reinitialization of the cross-encoder model when
+XPC connection errors occur on macOS (common in long-running daemon processes).
+"""
+
+import asyncio
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from hindsight_api.engine.cross_encoder import LocalSTCrossEncoder
+
+
+class TestCrossEncoderXPCErrorRecovery:
+    """Tests for XPC error detection and recovery in LocalSTCrossEncoder."""
+
+    @pytest.fixture
+    def cross_encoder(self):
+        """Create a LocalSTCrossEncoder instance."""
+        return LocalSTCrossEncoder(model_name="cross-encoder/ms-marco-TinyBERT-L-2-v2")
+
+    def test_is_xpc_error_detection(self, cross_encoder):
+        """Test that XPC errors are correctly detected."""
+        # Test various XPC error message formats
+        xpc_error = Exception("Compiler encountered XPC_ERROR_CONNECTION_INVALID (is the OS shutting down?)")
+        assert cross_encoder._is_xpc_error(xpc_error)
+
+        xpc_error2 = Exception("XPC error occurred")
+        assert cross_encoder._is_xpc_error(xpc_error2)
+
+        # Test that non-XPC errors are not detected
+        normal_error = Exception("Some other error")
+        assert not cross_encoder._is_xpc_error(normal_error)
+
+    @pytest.mark.asyncio
+    async def test_predict_with_xpc_recovery(self, cross_encoder):
+        """Test that predict() recovers from XPC errors by reinitializing."""
+        # Initialize the cross-encoder
+        await cross_encoder.initialize()
+
+        # Track calls to reinitialize
+        reinit_called = False
+        original_reinit = cross_encoder._reinitialize_model_sync
+
+        def track_reinit():
+            nonlocal reinit_called
+            reinit_called = True
+            original_reinit()
+
+        # Track predict attempts
+        predict_attempts = []
+        original_predict = cross_encoder._model.predict
+
+        def mock_predict(*args, **kwargs):
+            predict_attempts.append(1)
+            # Only fail on first attempt
+            if len(predict_attempts) == 1:
+                raise RuntimeError("Compiler encountered XPC_ERROR_CONNECTION_INVALID (is the OS shutting down?)")
+            else:
+                # After reinit: succeed
+                return original_predict(*args, **kwargs)
+
+        # Mock the initial predict to fail, reinit happens, then new model succeeds
+        with patch.object(cross_encoder, "_reinitialize_model_sync", side_effect=track_reinit):
+            with patch.object(cross_encoder._model, "predict", side_effect=mock_predict):
+                # This should trigger XPC error on first attempt, then recover and succeed
+                result = await cross_encoder.predict([("query", "document")])
+
+                # Verify we got a result
+                assert result is not None
+                assert len(result) == 1
+                assert isinstance(result[0], float)
+                assert reinit_called  # Should have reinitialized
+                assert len(predict_attempts) >= 1  # At least one attempt was made
+
+    @pytest.mark.asyncio
+    async def test_predict_fails_on_non_xpc_error(self, cross_encoder):
+        """Test that predict() does not retry for non-XPC errors."""
+        # Initialize the cross-encoder
+        await cross_encoder.initialize()
+
+        # Create a mock that raises a non-XPC error
+        def mock_predict(*args, **kwargs):
+            raise RuntimeError("Some other error")
+
+        # Patch the model's predict method
+        with patch.object(cross_encoder._model, "predict", side_effect=mock_predict):
+            # This should fail without retry
+            with pytest.raises(RuntimeError) as exc_info:
+                await cross_encoder.predict([("query", "document")])
+
+            assert "Some other error" in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_reinitialize_clears_model(self, cross_encoder):
+        """Test that _reinitialize_model_sync properly clears and reinits the model."""
+        # Initialize the cross-encoder
+        await cross_encoder.initialize()
+
+        original_model = cross_encoder._model
+        assert original_model is not None
+
+        # Reinitialize
+        cross_encoder._reinitialize_model_sync()
+
+        # Model should be reinitialized (new instance)
+        assert cross_encoder._model is not None
+        assert cross_encoder._model is not original_model
+
+        # Should still work
+        result = await cross_encoder.predict([("test query", "test document")])
+        assert len(result) == 1
+        assert isinstance(result[0], float)
+
+    @pytest.mark.asyncio
+    async def test_xpc_recovery_exhausts_retries(self, cross_encoder):
+        """Test that XPC recovery gives up after max retries."""
+        # Initialize the cross-encoder
+        await cross_encoder.initialize()
+
+        # Track reinit calls
+        reinit_count = 0
+        original_reinit = cross_encoder._reinitialize_model_sync
+
+        def track_and_fail_reinit():
+            nonlocal reinit_count
+            reinit_count += 1
+            # Call original reinit, but the new model will also be mocked to fail
+            original_reinit()
+            # After reinit, patch the new model too
+            cross_encoder._model.predict = MagicMock(
+                side_effect=RuntimeError("Compiler encountered XPC_ERROR_CONNECTION_INVALID")
+            )
+
+        # Mock that always raises XPC error
+        cross_encoder._model.predict = MagicMock(
+            side_effect=RuntimeError("Compiler encountered XPC_ERROR_CONNECTION_INVALID")
+        )
+
+        with patch.object(cross_encoder, "_reinitialize_model_sync", side_effect=track_and_fail_reinit):
+            # Should try once, reinitialize, try again, and fail
+            with pytest.raises(Exception) as exc_info:
+                await cross_encoder.predict([("query", "document")])
+
+            assert "XPC_ERROR_CONNECTION_INVALID" in str(exc_info.value) or "Failed to recover" in str(exc_info.value)
+            assert reinit_count == 1  # Should have tried to reinitialize once
@@ -0,0 +1,148 @@
+"""
+Tests for XPC error recovery in LocalSTEmbeddings.
+
+This tests the automatic reinitialization of the embedding model when
+XPC connection errors occur on macOS (common in long-running daemon processes).
+"""
+
+import asyncio
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from hindsight_api.engine.embeddings import LocalSTEmbeddings
+
+
+class TestXPCErrorRecovery:
+    """Tests for XPC error detection and recovery in LocalSTEmbeddings."""
+
+    @pytest.fixture
+    def embeddings(self):
+        """Create a LocalSTEmbeddings instance."""
+        return LocalSTEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2")
+
+    def test_is_xpc_error_detection(self, embeddings):
+        """Test that XPC errors are correctly detected."""
+        # Test various XPC error message formats
+        xpc_error = Exception("Compiler encountered XPC_ERROR_CONNECTION_INVALID (is the OS shutting down?)")
+        assert embeddings._is_xpc_error(xpc_error)
+
+        xpc_error2 = Exception("XPC error occurred")
+        assert embeddings._is_xpc_error(xpc_error2)
+
+        # Test that non-XPC errors are not detected
+        normal_error = Exception("Some other error")
+        assert not embeddings._is_xpc_error(normal_error)
+
+    @pytest.mark.asyncio
+    async def test_encode_with_xpc_recovery(self, embeddings):
+        """Test that encode() recovers from XPC errors by reinitializing."""
+        # Initialize the embeddings
+        await embeddings.initialize()
+
+        # Track calls to reinitialize
+        reinit_called = False
+        original_reinit = embeddings._reinitialize_model_sync
+
+        def track_reinit():
+            nonlocal reinit_called
+            reinit_called = True
+            original_reinit()
+
+        # Track encode attempts
+        encode_attempts = []
+        original_encode = embeddings._model.encode
+
+        def mock_encode(*args, **kwargs):
+            encode_attempts.append(1)
+            # Only fail on first attempt
+            if len(encode_attempts) == 1:
+                raise RuntimeError("Compiler encountered XPC_ERROR_CONNECTION_INVALID (is the OS shutting down?)")
+            else:
+                # After reinit: succeed
+                return original_encode(*args, **kwargs)
+
+        # Mock the initial encode to fail, reinit happens, then new model succeeds
+        with patch.object(embeddings, "_reinitialize_model_sync", side_effect=track_reinit):
+            with patch.object(embeddings._model, "encode", side_effect=mock_encode):
+                # This should trigger XPC error on first attempt, then recover and succeed
+                result = embeddings.encode(["test text"])
+
+                # Verify we got a result
+                assert result is not None
+                assert len(result) == 1
+                assert len(result[0]) > 0  # Should have embedding vector
+                assert reinit_called  # Should have reinitialized
+                assert len(encode_attempts) >= 1  # At least one attempt was made
+
+    @pytest.mark.asyncio
+    async def test_encode_fails_on_non_xpc_error(self, embeddings):
+        """Test that encode() does not retry for non-XPC errors."""
+        # Initialize the embeddings
+        await embeddings.initialize()
+
+        # Create a mock that raises a non-XPC error
+        def mock_encode(*args, **kwargs):
+            raise RuntimeError("Some other error")
+
+        # Patch the model's encode method
+        with patch.object(embeddings._model, "encode", side_effect=mock_encode):
+            # This should fail without retry
+            with pytest.raises(RuntimeError) as exc_info:
+                embeddings.encode(["test text"])
+
+            assert "Some other error" in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_reinitialize_clears_model(self, embeddings):
+        """Test that _reinitialize_model_sync properly clears and reinits the model."""
+        # Initialize the embeddings
+        await embeddings.initialize()
+
+        original_model = embeddings._model
+        assert original_model is not None
+
+        # Reinitialize
+        embeddings._reinitialize_model_sync()
+
+        # Model should be reinitialized (new instance)
+        assert embeddings._model is not None
+        assert embeddings._model is not original_model
+
+        # Should still work
+        result = embeddings.encode(["test"])
+        assert len(result) == 1
+        assert len(result[0]) > 0
+
+    @pytest.mark.asyncio
+    async def test_xpc_recovery_exhausts_retries(self, embeddings):
+        """Test that XPC recovery gives up after max retries."""
+        # Initialize the embeddings
+        await embeddings.initialize()
+
+        # Track reinit calls
+        reinit_count = 0
+        original_reinit = embeddings._reinitialize_model_sync
+
+        def track_and_fail_reinit():
+            nonlocal reinit_count
+            reinit_count += 1
+            # Call original reinit, but the new model will also be mocked to fail
+            original_reinit()
+            # After reinit, patch the new model too
+            embeddings._model.encode = MagicMock(
+                side_effect=RuntimeError("Compiler encountered XPC_ERROR_CONNECTION_INVALID")
+            )
+
+        # Mock that always raises XPC error
+        embeddings._model.encode = MagicMock(
+            side_effect=RuntimeError("Compiler encountered XPC_ERROR_CONNECTION_INVALID")
+        )
+
+        with patch.object(embeddings, "_reinitialize_model_sync", side_effect=track_and_fail_reinit):
+            # Should try once, reinitialize, try again, and fail
+            with pytest.raises(RuntimeError) as exc_info:
+                embeddings.encode(["test"])
+
+            assert "XPC_ERROR_CONNECTION_INVALID" in str(exc_info.value)
+            assert reinit_count == 1  # Should have tried to reinitialize once
@@ -1063,3 +1063,38 @@ 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}")
@@ -163,6 +163,12 @@ class TestToolNameNormalization:
        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"
+
    def test_is_done_tool(self):
        """Test _is_done_tool helper."""
        # Standard
@@ -174,9 +180,14 @@ 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:
@@ -527,6 +527,7 @@ 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(
@@ -538,6 +539,7 @@ 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)
@@ -545,6 +547,8 @@ class TestRemoteTEICrossEncoderConfig:
            assert encoder.batch_size == 256
            assert encoder.max_concurrent == 16

+        clear_config_cache()  # Clear cache after test
+

 # ============================================================================
 # TEI Reranker Performance Benchmark Tests
@@ -1,6 +1,6 @@
 [package]
 name = "hindsight-cli"
-version = "0.3.0"
+version = "0.4.1"
 edition = "2021"
 authors = ["Hindsight Team"]
 description = "A beautiful CLI for Hindsight - semantic memory system"
@@ -0,0 +1,125 @@
+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();
+}
@@ -7,14 +7,14 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
 """  # noqa: E501


-__version__ = "0.0.7"
+__version__ = "0.4.1"

 # import apis into sdk package
 from hindsight_client_api.api.banks_api import BanksApi
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.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.1.0\n"\
+               "Version of the API: 0.4.0\n"\
               "SDK Package Version: 0.0.7".\
               format(env=sys.platform, pyversion=sys.version)

@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -6,7 +6,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.1.0
+    The version of the OpenAPI document: 0.4.0
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Nicolò Boschi	c949191953	feat: add real-time timing breakdown logging for consolidation - Log timing breakdown after each batch (every 50 memories by default) - Log timing breakdown in progress logs (every 10 memories) - Shows recall, llm, embedding, db_write times incrementally - Includes avg time per memory for quick diagnosis - Helps diagnose performance issues in production without waiting for job completion Example output (every 10 memories): [CONSOLIDATION] bank=xyz progress: 10/39303 memories processed \| recall=2.09s, llm=11.03s, embedding=0.48s, db_write=0.02s Example output (per batch): [CONSOLIDATION] bank=xyz batch 1/50 memories: recall=7.3s, llm=57.5s, embedding=2.0s, db_write=0.09s \| avg=1.3s/memory	2026-01-29 17:37:01 +01:00
Nicolò Boschi	b8f06a09fb	Release v0.4.1 - Update version to 0.4.1 in all components - Python packages: hindsight-api, hindsight-dev, hindsight-all, hindsight-litellm, hindsight-embed - Python client: hindsight-clients/python - TypeScript client: hindsight-clients/typescript - Rust CLI: hindsight-cli - Control Plane: hindsight-control-plane - Helm chart	2026-01-29 11:25:28 +01:00
Nicolò Boschi	b43ef98686	feat: consolidation performance benchmark and optimization (#227 )	2026-01-29 11:24:15 +01:00
Nicolò Boschi	f17703fb37	doc: hide next version (#226 )	2026-01-29 08:46:21 +01:00
Nicolò Boschi	cfcc23c152	fix: /version endpoint return wrong version (#224 ) * fix: /version endpoint return wrong version * chore: update OpenAPI spec with correct version example	2026-01-29 08:40:01 +01:00
Chris Latimer	7300d5be4b	README video	2026-01-28 19:26:12 -07:00
Chris Latimer	81c82d9b93	README tweak	2026-01-28 19:21:15 -07:00
Chris Latimer	7551e65e55	Updated video in readme	2026-01-28 14:40:44 -07:00
DK09876andClaude Opus 4.5	94cc0a1270	fix: search_mental_models uuid type mismatch after text id migration (#225 ) The mental_models.id column was changed from UUID to TEXT in migration u6p7q8r9s0t1, but the exclude_ids filter in search_mental_models still cast the parameter as ::uuid[]. This caused every search_mental_models call during reflect to fail with "operator does not exist: text <> uuid", forcing the reflect agent to waste all 5 iterations on retries and producing degraded mental model content. Co-authored-by: Claude Opus 4.5 <[email protected]>	2026-01-28 20:04:19 +01:00
Nicolò BoschiandClaude Sonnet 4.5	67c47881cb	fix: add defensive error handling to PyTorch device detection (#221 ) * fix: include correct __version__ in python packages * fix(embed): force CPU mode for local models in daemon to prevent XPC crashes Adds HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU and HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU environment variables to force CPU-only operation for local sentence-transformer models. This prevents XPC_ERROR_CONNECTION_INVALID crashes on macOS when running in daemon mode. The issue occurs because PyTorch's MPS (Metal Performance Shaders) backend has unstable XPC connections in background processes, leading to C++ assertion failures that Python exception handlers cannot catch. Changes: - config.py: Add ENV__FORCE_CPU constants and config dataclass fields - embeddings.py: Add force_cpu parameter to LocalSTEmbeddings constructor - cross_encoder.py: Add force_cpu parameter to LocalSTCrossEncoder constructor - main.py: Set force CPU env vars in daemon mode, add fields to config constructor The daemon mode automatically enables force CPU for both embeddings and reranker, while normal mode allows hardware acceleration (GPU/MPS) as before. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]> fix: add defensive error handling to PyTorch device detection Wraps all PyTorch device detection code (torch.cuda.is_available() and torch.backends.mps.is_available()) in try-except blocks that gracefully fall back to CPU if any errors occur. This complements PR #218's force_cpu configuration by ensuring the code works reliably in all environments without configuration: - CI environments with CPU-only PyTorch builds - Systems without proper GPU/MPS support - Partial or misconfigured PyTorch installations The defensive approach prevents startup failures while still taking advantage of GPU/MPS acceleration when available and force_cpu is not explicitly set. Changes: - embeddings.py: Added try-except in initialize() and _reinitialize_model_sync() - cross_encoder.py: Added try-except in initialize() and _reinitialize_model_sync() * refactor: use get_config() for embeddings and reranker force_cpu Changes create_embeddings_from_env() and create_cross_encoder_from_env() to read configuration via get_config() instead of directly accessing os.environ. This ensures consistency across the codebase and properly respects the force_cpu configuration set by daemon mode. Changes: - embeddings.py: Use config.embeddings_local_model and config.embeddings_local_force_cpu - cross_encoder.py: Use config.reranker_local_model and config.reranker_local_force_cpu - Both: Use get_config() for provider, tei_url, and other config fields - Note: Some fields not in config (like max_concurrent for local reranker) still read from os.environ This fixes the issue where force_cpu was read inconsistently from environment variables instead of using the centralized config system. * test: clear config cache in test_create_from_env Fixes test failure caused by cached config not picking up environment variable changes in test. The test now calls clear_config_cache() before and after patching os.environ to ensure the factory function reads the test's env vars. * refactor: add reranker_local_max_concurrent to config system Adds reranker_local_max_concurrent to HindsightConfig dataclass and removes the workaround in create_cross_encoder_from_env() that was reading it directly from os.environ. Changes: - config.py: Add reranker_local_max_concurrent field to dataclass and from_env() - main.py: Add reranker_local_max_concurrent to manual config constructor - cross_encoder.py: Use config.reranker_local_max_concurrent instead of os.environ This completes the refactoring to use the centralized config system for all reranker configuration. --------- Co-authored-by: Claude Sonnet 4.5 <[email protected]>	2026-01-28 18:14:54 +01:00
Nicolò Boschi	2b72e1fd68	feat: support different default pg schema (#222 ) * feat: support different default pg schema * feat: support different default pg schema	2026-01-28 18:14:44 +01:00
Nicolò BoschiandChris Latimer	d2b797fff8	doc: improve readme (#223 ) * README updates * Add captions to video * Use cases and new banner --------- Co-authored-by: Chris Latimer <[email protected]>	2026-01-28 17:55:20 +01:00
Nicolò Boschi	fccbdfef16	fix: include correct __version__ in python packages (#218 ) Updates: - hindsight-api/hindsight_api/__init__.py: bump __version__ to 0.4.0 - scripts/release.sh: add logic to update __version__ in Python __init__.py files during release	2026-01-28 17:25:17 +01:00
Nicolò Boschi	20f2b92069	doc: release notes for 0.4.0 (#217 ) * doc: release notes for 0.4.0 * doc: release notes for 0.4.0 * doc: release notes for 0.4.0 * doc: release notes for 0.4.0	2026-01-28 16:54:05 +01:00
Nicolò Boschi	1bf90358c3	doc: add blog (#201 ) * doc: introduce mental models blog post Write blog post introducing Mental Models in Hindsight 0.4.0: - Evolution from observations and opinions - How mental models work (consolidation, evidence tracking) - Breaking changes and migration path - Environment variable to enable (experimental) - Agentic reflect explanation * updates * Update 2026-01-26-learning-capabilities.md * fix: doc build issues - Add missing code snippets for versioned docs (recall-opinions-only, recall-include-entities, bank-background) - Fix broken links by using relative paths for version compatibility - Update blog post title to sentence case - Clear versions.json since v0.3 versioned docs don't exist yet - Enable INCLUDE_CURRENT_VERSION in build script * fix: update doc links after rebase - Fix blog post to link to correct pages (/developer/api/mental-models and /developer/observations) - Fix CLI docs to link to /api-reference instead of /api * feat: add directives section to blog post - Update intro to mention three layers of knowledge - Add concise Directives section for compliance/guardrails - Add directives to resources section - Keep focus on learning capabilities (observations and mental models) * fix: revert intro to focus on learning capabilities only Directives are a separate feature for compliance/guardrails, not a learning capability. The blog post is about observations and mental models.	2026-01-28 15:42:14 +01:00
Nicolò Boschi	2118d0a7cd	Release v0.4.0 - Update version to 0.4.0 in all components - Python packages: hindsight-api, hindsight-dev, hindsight-all, hindsight-litellm, hindsight-embed - Python client: hindsight-clients/python - TypeScript client: hindsight-clients/typescript - Rust CLI: hindsight-cli - Control Plane: hindsight-control-plane - Helm chart	2026-01-28 15:04:43 +01:00
Nicolò Boschi	e5fc6eedb6	fix(embed): daemon process XPC connection crash on macos (#215 ) * fix(embed): daemon process XPC connection crash on macos * other fix	2026-01-28 14:52:31 +01:00
Nicolò Boschi	bb0e0316a7	fix: graph endpoint not showing links for observations (#214 )	2026-01-28 14:51:25 +01:00