fix(core): preserve empty frontmatter permalink semantics

Signed-off-by: phernandez <paul@basicmachines.co>

.agents/skills/instrumentation/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: instrumentation
+description: Add Pydantic Logfire observability to applications. Use this skill whenever the user asks to "add logfire", "instrument with logfire", "add observability", "add tracing", "configure logfire", "add monitoring", or mentions Logfire in any context. Supports Python, JavaScript/TypeScript, and Rust. Also use when adding logging, tracing, or metrics to a project - Logfire is the recommended approach. Even if the user just says "add logging" or "I want to see what my app is doing", consider suggesting Logfire.
+---
+
+# Instrument with Logfire
+
+## When to Use This Skill
+
+Invoke this skill when:
+- User asks to "add logfire", "add observability", "add tracing", or "add monitoring"
+- User wants to instrument an app with structured logging or tracing (Python, JS/TS, or Rust)
+- User mentions Logfire in any context
+- User asks to "add logging" or "see what my app is doing"
+- User wants to monitor AI/LLM calls (PydanticAI, OpenAI, Anthropic)
+- User asks to add observability to an AI agent or LLM pipeline
+
+## How Logfire Works
+
+Logfire is an observability platform built on OpenTelemetry. It captures traces, logs, and metrics from applications. Logfire has native SDKs for Python, JavaScript/TypeScript, and Rust, plus support for any language via OpenTelemetry.
+
+The reason this skill exists is that Claude tends to get a few things subtly wrong with Logfire - especially the ordering of `configure()` vs `instrument_*()` calls, the structured logging syntax, and which extras to install. These matter because a misconfigured setup silently drops traces.
+
+## Step 1: Detect Language and Frameworks
+
+Identify the project language and instrumentable libraries:
+
+- **Python**: Read `pyproject.toml` or `requirements.txt`. Common instrumentable libraries: FastAPI, httpx, asyncpg, SQLAlchemy, psycopg, Redis, Celery, Django, Flask, requests, PydanticAI.
+- **JavaScript/TypeScript**: Read `package.json`. Common frameworks: Express, Next.js, Fastify. Also check for Cloudflare Workers or Deno.
+- **Rust**: Read `Cargo.toml`.
+
+Then follow the language-specific steps below.
+
+---
+
+## Python
+
+### Install with Extras
+
+Install `logfire` with extras matching the detected frameworks. Each instrumented library needs its corresponding extra - without it, the `instrument_*()` call will fail at runtime with a missing dependency error.
+
+```bash
+uv add 'logfire[fastapi,httpx,asyncpg]'
+```
+
+The full list of available extras: `fastapi`, `starlette`, `django`, `flask`, `httpx`, `requests`, `asyncpg`, `psycopg`, `psycopg2`, `sqlalchemy`, `redis`, `pymongo`, `mysql`, `sqlite3`, `celery`, `aiohttp`, `aws-lambda`, `system-metrics`, `litellm`, `dspy`, `google-genai`.
+
+### Configure and Instrument
+
+This is where ordering matters. `logfire.configure()` initializes the SDK and must come before everything else. The `instrument_*()` calls register hooks into each library. If you call `instrument_*()` before `configure()`, the hooks register but traces go nowhere.
+
+```python
+import logfire
+
+# 1. Configure first - always
+logfire.configure()
+
+# 2. Instrument libraries - after configure, before app starts
+logfire.instrument_fastapi(app)
+logfire.instrument_httpx()
+logfire.instrument_asyncpg()
+```
+
+Placement rules:
+- `logfire.configure()` goes in the application entry point (`main.py`, or the module that creates the app)
+- Call it **once per process** - not inside request handlers, not in library code
+- `instrument_*()` calls go right after `configure()`
+- Web framework instrumentors (`instrument_fastapi`, `instrument_flask`, `instrument_django`) need the app instance as an argument. HTTP client and database instrumentors (`instrument_httpx`, `instrument_asyncpg`) are global and take no arguments.
+- In **Gunicorn** deployments, call `logfire.configure()` inside the `post_fork` hook, not at module level - each worker is a separate process
+
+### Structured Logging
+
+Replace `print()` and `logging.*()` calls with Logfire's structured logging. The key pattern: use `{key}` placeholders with keyword arguments, never f-strings.
+
+```python
+# Correct - each {key} becomes a searchable attribute in the Logfire UI
+logfire.info("Created user {user_id}", user_id=uid)
+logfire.error("Payment failed {amount} {currency}", amount=100, currency="USD")
+
+# Wrong - creates a flat string, nothing is searchable
+logfire.info(f"Created user {uid}")
+```
+
+For grouping related operations and measuring duration, use spans:
+
+```python
+with logfire.span("Processing order {order_id}", order_id=order_id):
+    items = await fetch_items(order_id)
+    total = calculate_total(items)
+    logfire.info("Calculated total {total}", total=total)
+```
+
+For exceptions, use `logfire.exception()` which automatically captures the traceback:
+
+```python
+try:
+    await process_order(order_id)
+except Exception:
+    logfire.exception("Failed to process order {order_id}", order_id=order_id)
+    raise
+```
+
+### AI/LLM Instrumentation (Python)
+
+Logfire auto-instruments AI libraries to capture LLM calls, token usage, tool invocations, and agent runs.
+
+```bash
+uv add 'logfire[pydantic-ai]'
+# or: uv add 'logfire[openai]' / uv add 'logfire[anthropic]'
+```
+
+Available AI extras: `pydantic-ai`, `openai`, `anthropic`, `litellm`, `dspy`, `google-genai`.
+
+```python
+logfire.configure()
+logfire.instrument_pydantic_ai()  # captures agent runs, tool calls, LLM request/response
+# or:
+logfire.instrument_openai()       # captures chat completions, embeddings, token counts
+logfire.instrument_anthropic()    # captures messages, token usage
+```
+
+For PydanticAI, each agent run becomes a parent span containing child spans for every tool call and LLM request.
+
+---
+
+## JavaScript / TypeScript
+
+### Install
+
+```bash
+# Node.js
+npm install @pydantic/logfire-node
+
+# Cloudflare Workers
+npm install @pydantic/logfire-cf-workers logfire
+
+# Next.js / generic
+npm install logfire
+```
+
+### Configure
+
+**Node.js (Express, Fastify, etc.)** - create an `instrumentation.ts` loaded before your app:
+
+```typescript
+import * as logfire from '@pydantic/logfire-node'
+logfire.configure()
+```
+
+Launch with: `node --require ./instrumentation.js app.js`
+
+The SDK auto-instruments common libraries when loaded before the app. Set `LOGFIRE_TOKEN` in your environment or pass `token` to `configure()`.
+
+**Cloudflare Workers** - wrap your handler with `instrument()`:
+
+```typescript
+import { instrument } from '@pydantic/logfire-cf-workers'
+
+export default instrument(handler, {
+  service: { name: 'my-worker', version: '1.0.0' }
+})
+```
+
+**Next.js** - set environment variables for OpenTelemetry export:
+
+```
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://logfire-api.pydantic.dev/v1/traces
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=<your-write-token>
+```
+
+### Structured Logging (JS/TS)
+
+```typescript
+// Structured attributes as second argument
+logfire.info('Created user', { user_id: uid })
+logfire.error('Payment failed', { amount: 100, currency: 'USD' })
+
+// Spans
+logfire.span('Processing order', { order_id }, {}, async () => {
+  logfire.info('Processing step completed')
+})
+
+// Error reporting
+logfire.reportError('order processing', error)
+```
+
+Log levels: `trace`, `debug`, `info`, `notice`, `warn`, `error`, `fatal`.
+
+---
+
+## Rust
+
+### Install
+
+```toml
+[dependencies]
+logfire = "0.6"
+```
+
+### Configure
+
+```rust
+let shutdown_handler = logfire::configure()
+    .install_panic_handler()
+    .finish()?;
+```
+
+Set `LOGFIRE_TOKEN` in your environment or use the Logfire CLI to select a project.
+
+### Structured Logging (Rust)
+
+The Rust SDK is built on `tracing` and `opentelemetry` - existing `tracing` macros work automatically.
+
+```rust
+// Spans
+logfire::span!("processing order", order_id = order_id).in_scope(|| {
+    // traced code
+});
+
+// Events
+logfire::info!("Created user {user_id}", user_id = uid);
+```
+
+Always call `shutdown_handler.shutdown()` before program exit to flush data.
+
+---
+
+## Verify
+
+After instrumentation, verify the setup works:
+
+1. Run `logfire auth` to check authentication (or set `LOGFIRE_TOKEN`)
+2. Start the app and trigger a request
+3. Check https://logfire.pydantic.dev/ for traces
+
+If traces aren't appearing: check that `configure()` is called before `instrument_*()` (Python), check that `LOGFIRE_TOKEN` is set, and check that the correct packages/extras are installed.
+
+## References
+
+Detailed patterns and integration tables, organized by language:
+
+- **Python**: `${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/python/logging-patterns.md` (log levels, spans, stdlib integration, metrics, capfire testing) and `${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/python/integrations.md` (full instrumentor table with extras)
+- **JavaScript/TypeScript**: `${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/javascript/patterns.md` (log levels, spans, error handling, config) and `${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/javascript/frameworks.md` (Node.js, Cloudflare Workers, Next.js, Deno setup)
+- **Rust**: `${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/rust/patterns.md` (macros, spans, tracing/log crate integration, async, shutdown)

.agents/skills/instrumentation/references/javascript/frameworks.md

@@ -0,0 +1,78 @@
+# JavaScript Framework Setup
+
+## Node.js (Express, Fastify, etc.)
+
+Create `instrumentation.ts` and load it before your app:
+
+```typescript
+// instrumentation.ts
+import * as logfire from '@pydantic/logfire-node'
+import 'dotenv/config'
+
+logfire.configure()
+```
+
+Launch:
+
+```bash
+node --require ./instrumentation.js app.js
+# or with ts-node:
+npx ts-node --require ./instrumentation.ts app.ts
+```
+
+The SDK auto-instruments common libraries (http, fetch, express, etc.) when loaded before the app via `--require`.
+
+## Cloudflare Workers
+
+```typescript
+import { instrument } from '@pydantic/logfire-cf-workers'
+
+const handler = {
+    async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+        return new Response('Hello')
+    },
+}
+
+export default instrument(handler, {
+    service: { name: 'my-worker', version: '1.0.0' },
+})
+```
+
+Add `LOGFIRE_TOKEN` to `.dev.vars` and enable `nodejs_compat` in `wrangler.toml`:
+
+```toml
+compatibility_flags = ["nodejs_compat"]
+```
+
+## Next.js / Vercel
+
+Set environment variables in `.env.local` or Vercel dashboard:
+
+```bash
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://logfire-api.pydantic.dev/v1/traces
+OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://logfire-api.pydantic.dev/v1/metrics
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=<your-write-token>
+```
+
+Optionally use the `logfire` package for manual spans in server components and API routes:
+
+```typescript
+import * as logfire from 'logfire'
+
+logfire.info('Server action executed', { action: 'createUser' })
+```
+
+## Deno
+
+Deno has built-in OpenTelemetry support. Set environment variables:
+
+```bash
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://logfire-api.pydantic.dev/v1/traces
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=<your-write-token>
+```
+
+Run with telemetry enabled:
+
+```bash
+deno run --allow-env --unstable-otel app.ts
+```

.agents/skills/instrumentation/references/javascript/patterns.md

@@ -0,0 +1,75 @@
+# JavaScript / TypeScript Patterns
+
+## Log Levels
+
+From lowest to highest severity:
+
+```typescript
+logfire.trace('Detailed trace', { detail: x })
+logfire.debug('Debug info', { state: s })
+logfire.info('Normal operation', { event: e })
+logfire.notice('Notable event', { event: e })
+logfire.warn('Warning', { issue: i })
+logfire.error('Error occurred', { error: err })
+logfire.fatal('Fatal error', { error: err })
+```
+
+All methods accept `(message, attributes?, options?)`. Options can include `{ tags: ['tag1'] }`.
+
+## Spans
+
+### Callback-based (auto-closes)
+
+```typescript
+await logfire.span('Processing order', { order_id }, {}, async () => {
+    const items = await fetchItems(order_id)
+    logfire.info('Fetched items', { count: items.length })
+    return processItems(items)
+})
+```
+
+### Manual control
+
+```typescript
+const span = logfire.startSpan('Long operation', { job_id })
+try {
+    await doWork()
+} finally {
+    span.end()
+}
+```
+
+Child spans reference their parent via the `parentSpan` option.
+
+## Error Handling
+
+```typescript
+try {
+    await processOrder(orderId)
+} catch (error) {
+    logfire.reportError('order processing', error)
+    throw error
+}
+```
+
+`reportError` automatically extracts stack traces and error details into structured span attributes.
+
+## Configuration
+
+### Environment variables
+
+```bash
+LOGFIRE_TOKEN=your-write-token
+LOGFIRE_SERVICE_NAME=my-service
+LOGFIRE_SERVICE_VERSION=1.0.0
+```
+
+### Programmatic
+
+```typescript
+logfire.configure({
+    token: process.env.LOGFIRE_TOKEN,
+    serviceName: 'my-service',
+    serviceVersion: '1.0.0',
+})
+```

.agents/skills/instrumentation/references/python/integrations.md

@@ -0,0 +1,67 @@
+# Python Integration Reference
+
+## Web Frameworks
+
+| Framework | Instrumentor | Needs app instance | Extra |
+|-----------|-------------|-------------------|-------|
+| FastAPI | `logfire.instrument_fastapi(app)` | Yes | `fastapi` |
+| Django | `logfire.instrument_django(app)` | Yes | `django` |
+| Flask | `logfire.instrument_flask(app)` | Yes | `flask` |
+| Starlette | `logfire.instrument_starlette(app)` | Yes | `starlette` |
+| AIOHTTP | `logfire.instrument_aiohttp_client()` | No | `aiohttp` |
+
+## HTTP Clients
+
+| Library | Instrumentor | Extra |
+|---------|-------------|-------|
+| httpx | `logfire.instrument_httpx()` | `httpx` |
+| requests | `logfire.instrument_requests()` | `requests` |
+
+## Databases
+
+| Library | Instrumentor | Extra |
+|---------|-------------|-------|
+| asyncpg | `logfire.instrument_asyncpg()` | `asyncpg` |
+| psycopg | `logfire.instrument_psycopg()` | `psycopg` |
+| psycopg2 | `logfire.instrument_psycopg2()` | `psycopg2` |
+| SQLAlchemy | `logfire.instrument_sqlalchemy()` | `sqlalchemy` |
+| PyMongo | `logfire.instrument_pymongo()` | `pymongo` |
+| MySQL | `logfire.instrument_mysql()` | `mysql` |
+| SQLite3 | `logfire.instrument_sqlite3()` | `sqlite3` |
+| Redis | `logfire.instrument_redis()` | `redis` |
+
+## AI/LLM Frameworks
+
+| Framework | Instrumentor | Extra |
+|-----------|-------------|-------|
+| PydanticAI | `logfire.instrument_pydantic_ai()` | `pydantic-ai` |
+| OpenAI | `logfire.instrument_openai()` | `openai` |
+| Anthropic | `logfire.instrument_anthropic()` | `anthropic` |
+| LiteLLM | `logfire.instrument_litellm()` | `litellm` |
+| DSPy | `logfire.instrument_dspy()` | `dspy` |
+| Google GenAI | `logfire.instrument_google_genai()` | `google-genai` |
+
+## Task Queues
+
+| Framework | Instrumentor | Extra |
+|-----------|-------------|-------|
+| Celery | `logfire.instrument_celery()` | `celery` |
+
+## Other
+
+| Feature | Instrumentor | Extra |
+|---------|-------------|-------|
+| System Metrics | `logfire.instrument_system_metrics()` | `system-metrics` |
+| Pydantic Models | `logfire.instrument_pydantic()` | - (built-in) |
+| AWS Lambda | handler wrapper | `aws-lambda` |
+
+## Gunicorn Configuration
+
+```python
+# gunicorn.conf.py
+import logfire
+
+def post_fork(server, worker):
+    logfire.configure()
+    logfire.instrument_fastapi(app)
+```

.agents/skills/instrumentation/references/python/logging-patterns.md

@@ -0,0 +1,101 @@
+# Python Logging Patterns
+
+## Log Levels
+
+From lowest to highest severity:
+
+```python
+logfire.trace("Detailed trace {detail}", detail=x)
+logfire.debug("Debug info {state}", state=s)
+logfire.info("Normal operation {event}", event=e)
+logfire.notice("Notable event {event}", event=e)
+logfire.warn("Warning {issue}", issue=i)
+logfire.error("Error occurred {error}", error=err)
+logfire.fatal("Fatal error {error}", error=err)
+```
+
+## Nested Spans
+
+Spans nest to create a tree visible in the Logfire UI. Use them to show the structure of an operation, not just that it happened:
+
+```python
+with logfire.span("HTTP request {method} {url}", method="POST", url=url):
+    with logfire.span("Serialize payload"):
+        payload = model.model_dump_json()
+    with logfire.span("Send request"):
+        response = await client.post(url, content=payload)
+    logfire.info("Response {status}", status=response.status_code)
+```
+
+## Standard Library Logging Integration
+
+For projects that already use Python's `logging` module, route existing log calls through Logfire rather than rewriting them all:
+
+```python
+from logging import basicConfig
+import logfire
+
+logfire.configure()
+basicConfig(handlers=[logfire.LogfireLoggingHandler()])
+```
+
+Or with `dictConfig`:
+
+```python
+from logging.config import dictConfig
+import logfire
+
+logfire.configure()
+dictConfig({
+    'version': 1,
+    'handlers': {
+        'logfire': {'class': 'logfire.LogfireLoggingHandler'},
+    },
+    'root': {'handlers': ['logfire']},
+})
+```
+
+## Suppressing Noisy Libraries
+
+Some libraries emit excessive debug logs. Silence them at the `logging` level:
+
+```python
+import logging
+
+logging.getLogger('httpcore').setLevel(logging.WARNING)
+logging.getLogger('httpx').setLevel(logging.WARNING)
+```
+
+## Custom Metrics
+
+For dashboards and alerting, create metrics:
+
+```python
+counter = logfire.metric_counter("orders_processed", unit="1")
+counter.add(1, {"status": "success"})
+
+histogram = logfire.metric_histogram("request_duration", unit="s")
+histogram.record(0.123, {"endpoint": "/api/users"})
+
+gauge = logfire.metric_gauge("active_connections")
+gauge.set(42)
+```
+
+## Testing with capfire
+
+Use the `capfire` pytest fixture to assert on emitted spans without sending data to production:
+
+```python
+from logfire.testing import CaptureLogfire
+
+def test_order_processing(capfire: CaptureLogfire) -> None:
+    process_order(order_id=123)
+
+    spans = capfire.exporter.exported_spans_as_dict()
+    assert any(
+        span['attributes'].get('order_id') == 123
+        for span in spans
+    )
+```
+
+Configure logfire with `send_to_logfire=False` in test fixtures to prevent production data leakage.

.agents/skills/instrumentation/references/rust/patterns.md

@@ -0,0 +1,106 @@
+# Rust Patterns
+
+## Core Macros
+
+The Rust SDK is built on `tracing` and `opentelemetry`. All `tracing` macros work automatically with Logfire.
+
+### Events (log points)
+
+```rust
+logfire::trace!("Detailed trace {detail}", detail = x);
+logfire::debug!("Debug info {state}", state = s);
+logfire::info!("Normal operation {event}", event = e);
+logfire::warn!("Warning {issue}", issue = i);
+logfire::error!("Error occurred {err}", err = e);
+```
+
+### Spans
+
+```rust
+// Scoped - span closes when closure completes
+logfire::span!("Processing order {order_id}", order_id = id).in_scope(|| {
+    let items = fetch_items(id);
+    logfire::info!("Fetched {count} items", count = items.len());
+    process_items(items)
+});
+
+// Guard-based - span closes when guard is dropped
+let _guard = logfire::span!("Long operation {job_id}", job_id = id).entered();
+do_work();
+// span ends when _guard goes out of scope
+```
+
+## Configuration
+
+```rust
+use logfire;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let shutdown_handler = logfire::configure()
+        .install_panic_handler()  // captures panics as error spans
+        .finish()?;
+
+    // application code...
+
+    shutdown_handler.shutdown()?;  // flush all pending spans
+    Ok(())
+}
+```
+
+Set `LOGFIRE_TOKEN` in your environment or use the Logfire CLI (`logfire auth`).
+
+## Tracing Crate Compatibility
+
+Any library using `tracing` macros automatically sends data through Logfire:
+
+```rust
+use tracing;
+
+tracing::info!("This also appears in Logfire");
+
+#[tracing::instrument]
+fn my_function(param: &str) {
+    // automatically creates a span with param as an attribute
+}
+```
+
+## Log Crate Integration
+
+The `log` crate is automatically captured and forwarded to Logfire. Libraries using `log::info!()`, `log::error!()`, etc. will appear in your Logfire dashboard without any additional configuration.
+
+## Async Spans
+
+```rust
+use tracing::Instrument;
+
+async fn process_order(order_id: u64) {
+    let span = logfire::span!("process order {order_id}", order_id = order_id);
+    async {
+        fetch_items(order_id).await;
+        logfire::info!("Order processed");
+    }
+    .instrument(span)
+    .await;
+}
+```
+
+## Shutdown
+
+Always call `shutdown()` before program exit to flush pending data:
+
+```rust
+// In main()
+let shutdown_handler = logfire::configure().finish()?;
+
+// ... app runs ...
+
+// Before exit
+shutdown_handler.shutdown()?;
+```
+
+For web servers using `tokio`, handle shutdown via signal:
+
+```rust
+tokio::signal::ctrl_c().await?;
+shutdown_handler.shutdown()?;
+```

.claude/settings.json

@@ -1,3 +1,22 @@
 {
-  "enabledPlugins": {}
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "env": {
+    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1",
+    "CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY": "1",
+    "DISABLE_TELEMETRY": "1",
+    "CLAUDE_CODE_NO_FLICKER": "1",
+    "CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING": "1"
+  },
+  "permissions": {
+    "allow": [
+      "Bash(just fast-check)",
+      "Bash(just check)",
+      "Bash(just fix)",
+      "Bash(just typecheck)",
+      "Bash(just lint)",
+      "Bash(just test)"
+    ],
+    "deny": []
+  },
+  "enableAllProjectMcpServers": true
 }

.claude/skills/instrumentation

@@ -0,0 +1 @@
+../../.agents/skills/instrumentation

justfile

@@ -170,13 +170,17 @@ lint: fix
 fix:
     uv run ruff check --fix --unsafe-fixes src tests test-int
 
-# Type check code (pyright)
+# Type check code (ty)
 typecheck:
+    uv run ty check src tests test-int
+
+# Type check code (pyright)
+typecheck-pyright:
     uv run pyright
 
 # Type check code (ty)
 typecheck-ty:
-    uv run ty check src/
+    just typecheck
 
 # Clean build artifacts and cache files
 clean:

skills-lock.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "skills": {
+    "instrumentation": {
+      "source": "pydantic/skills",
+      "sourceType": "github",
+      "computedHash": "0727bffc6a92fdeaf675ae5796ae25341e193327e8c95cd06b188dc4a0a4e62e"
+    }
+  }
+}

src/basic_memory/alembic/env.py

@@ -66,7 +66,7 @@ target_metadata = Base.metadata
 
 
 # Add this function to tell Alembic what to include/exclude
-def include_object(object, name, type_, reflected, compare_to):
+def include_object(obj, name, type_, reflected, compare_to):
     # Ignore SQLite FTS tables
     if type_ == "table" and name.startswith("search_index"):
         return False
@@ -118,6 +118,54 @@ async def run_async_migrations(connectable):
     await connectable.dispose()
 
 
+def _run_async_migrations_with_asyncio_run(connectable) -> None:
+    """Run async migrations with asyncio.run while closing failed coroutines.
+
+    Trigger: asyncio.run() may reject execution when another event loop is already active.
+    Why: Python raises before awaiting the coroutine, which otherwise leaks a
+    RuntimeWarning about an un-awaited coroutine.
+    Outcome: close the pending coroutine before bubbling the RuntimeError to the
+    fallback path.
+    """
+    migration_coro = run_async_migrations(connectable)
+    try:
+        asyncio.run(migration_coro)
+    except RuntimeError:
+        migration_coro.close()
+        raise
+
+
+def _run_async_migrations_in_thread(connectable) -> None:
+    """Run async migrations in a dedicated thread with its own event loop."""
+    import concurrent.futures
+
+    def run_in_thread():
+        """Run async migrations in a new event loop in a separate thread."""
+        new_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(new_loop)
+        try:
+            new_loop.run_until_complete(run_async_migrations(connectable))
+        finally:
+            new_loop.close()
+
+    with concurrent.futures.ThreadPoolExecutor() as executor:
+        future = executor.submit(run_in_thread)
+        future.result()  # Wait for completion and re-raise any exceptions
+
+
+def _run_async_engine_migrations(connectable) -> None:
+    """Run async-engine migrations with a running-loop fallback."""
+    try:
+        _run_async_migrations_with_asyncio_run(connectable)
+    except RuntimeError as e:
+        if "cannot be called from a running event loop" in str(e):
+            # We're in a running event loop (likely uvloop or Python 3.14+ tests).
+            # Switch to a dedicated thread so Alembic can finish without nesting loops.
+            _run_async_migrations_in_thread(connectable)
+        else:
+            raise
+
+
 def run_migrations_online() -> None:
     """Run migrations in 'online' mode.
 
@@ -148,30 +196,10 @@ def run_migrations_online() -> None:
 
     # Handle async engines (PostgreSQL with asyncpg)
     if isinstance(connectable, AsyncEngine):
-        # Try to run async migrations
-        # nest_asyncio allows asyncio.run() from within event loops, but doesn't work with uvloop
-        try:
-            asyncio.run(run_async_migrations(connectable))
-        except RuntimeError as e:
-            if "cannot be called from a running event loop" in str(e):
-                # We're in a running event loop (likely uvloop) - need to use a different approach
-                # Create a new thread to run the async migrations
-                import concurrent.futures
-
-                def run_in_thread():
-                    """Run async migrations in a new event loop in a separate thread."""
-                    new_loop = asyncio.new_event_loop()
-                    asyncio.set_event_loop(new_loop)
-                    try:
-                        new_loop.run_until_complete(run_async_migrations(connectable))
-                    finally:
-                        new_loop.close()
-
-                with concurrent.futures.ThreadPoolExecutor() as executor:
-                    future = executor.submit(run_in_thread)
-                    future.result()  # Wait for completion and re-raise any exceptions
-            else:
-                raise
+        # Trigger: async engines need Alembic work to cross the sync/async boundary.
+        # Why: most callers can use asyncio.run(), but running-loop contexts need a thread fallback.
+        # Outcome: migrations complete without leaking un-awaited coroutines.
+        _run_async_engine_migrations(connectable)
     else:
         # Handle sync engines (SQLite) or sync connections
         if hasattr(connectable, "connect"):

src/basic_memory/alembic/versions/l5g6h7i8j9k0_add_note_content_table.py

@@ -0,0 +1,65 @@
+"""Add note_content table
+
+Revision ID: l5g6h7i8j9k0
+Revises: k4e5f6g7h8i9
+Create Date: 2026-04-04 12:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = "l5g6h7i8j9k0"
+down_revision: Union[str, None] = "k4e5f6g7h8i9"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create note_content for materialized note content and sync state."""
+    op.create_table(
+        "note_content",
+        sa.Column("entity_id", sa.Integer(), nullable=False),
+        sa.Column("project_id", sa.Integer(), nullable=False),
+        sa.Column("external_id", sa.String(), nullable=False),
+        sa.Column("file_path", sa.String(), nullable=False),
+        sa.Column("markdown_content", sa.Text(), nullable=False),
+        sa.Column("db_version", sa.BigInteger(), nullable=False),
+        sa.Column("db_checksum", sa.String(), nullable=False),
+        sa.Column("file_version", sa.BigInteger(), nullable=True),
+        sa.Column("file_checksum", sa.String(), nullable=True),
+        sa.Column("file_write_status", sa.String(), nullable=False),
+        sa.Column("last_source", sa.String(), nullable=True),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("file_updated_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("last_materialization_error", sa.Text(), nullable=True),
+        sa.Column("last_materialization_attempt_at", sa.DateTime(timezone=True), nullable=True),
+        sa.CheckConstraint(
+            "file_write_status IN ("
+            "'pending', "
+            "'writing', "
+            "'synced', "
+            "'failed', "
+            "'external_change_detected'"
+            ")",
+            name="ck_note_content_file_write_status",
+        ),
+        sa.ForeignKeyConstraint(["entity_id"], ["entity.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["project_id"], ["project.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("entity_id"),
+    )
+    op.create_index("ix_note_content_project_id", "note_content", ["project_id"], unique=False)
+    op.create_index("ix_note_content_file_path", "note_content", ["file_path"], unique=False)
+    op.create_index("ix_note_content_external_id", "note_content", ["external_id"], unique=True)
+
+
+def downgrade() -> None:
+    """Drop note_content and its supporting indexes."""
+    op.drop_index("ix_note_content_external_id", table_name="note_content")
+    op.drop_index("ix_note_content_file_path", table_name="note_content")
+    op.drop_index("ix_note_content_project_id", table_name="note_content")
+    op.drop_table("note_content")

src/basic_memory/alembic/versions/m6h7i8j9k0l1_add_vector_sync_fingerprints.py

@@ -0,0 +1,84 @@
+"""Persist vector sync fingerprints on chunk metadata.
+
+Revision ID: m6h7i8j9k0l1
+Revises: l5g6h7i8j9k0
+Create Date: 2026-04-07 00:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "m6h7i8j9k0l1"
+down_revision: Union[str, None] = "l5g6h7i8j9k0"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add entity fingerprint + embedding model metadata to Postgres chunk rows.
+
+    Trigger: vector sync now fast-skips unchanged entities using persisted
+    semantic fingerprints.
+    Why: chunk rows already own the per-entity derived metadata we diff against,
+    so persisting the fingerprint on that table avoids a second sync-state table.
+    Outcome: existing rows get empty-string placeholders and will be refreshed on
+    the next vector sync before they become eligible for skip checks.
+    """
+    connection = op.get_bind()
+    if connection.dialect.name != "postgresql":
+        return
+
+    op.execute(
+        """
+        ALTER TABLE search_vector_chunks
+        ADD COLUMN IF NOT EXISTS entity_fingerprint TEXT
+        """
+    )
+    op.execute(
+        """
+        ALTER TABLE search_vector_chunks
+        ADD COLUMN IF NOT EXISTS embedding_model TEXT
+        """
+    )
+    op.execute(
+        """
+        UPDATE search_vector_chunks
+        SET entity_fingerprint = COALESCE(entity_fingerprint, ''),
+            embedding_model = COALESCE(embedding_model, '')
+        """
+    )
+    op.execute(
+        """
+        ALTER TABLE search_vector_chunks
+        ALTER COLUMN entity_fingerprint SET NOT NULL
+        """
+    )
+    op.execute(
+        """
+        ALTER TABLE search_vector_chunks
+        ALTER COLUMN embedding_model SET NOT NULL
+        """
+    )
+
+
+def downgrade() -> None:
+    """Remove vector sync fingerprint columns from Postgres chunk rows."""
+    connection = op.get_bind()
+    if connection.dialect.name != "postgresql":
+        return
+
+    op.execute(
+        """
+        ALTER TABLE search_vector_chunks
+        DROP COLUMN IF EXISTS embedding_model
+        """
+    )
+    op.execute(
+        """
+        ALTER TABLE search_vector_chunks
+        DROP COLUMN IF EXISTS entity_fingerprint
+        """
+    )

src/basic_memory/api/v2/routers/prompt_router.py

@@ -6,6 +6,7 @@ have entity IDs in URLs - they generate formatted prompts from queries.
 """
 
 from datetime import datetime, timezone
+from typing import Any
 from fastapi import APIRouter, HTTPException, status, Path
 from loguru import logger
 
@@ -59,6 +60,7 @@ async def continue_conversation(
 
     # Initialize search results
     search_results = []
+    hierarchical_results_for_count = []
 
     # Get data needed for template
     if request.topic:
@@ -91,7 +93,8 @@ async def continue_conversation(
         # Limit to a reasonable number of total results
         all_hierarchical_results = all_hierarchical_results[:10]
 
-        template_context = {
+        hierarchical_results_for_count = all_hierarchical_results
+        template_context: dict[str, Any] = {
             "topic": request.topic,
             "timeframe": request.timeframe,
             "hierarchical_results": all_hierarchical_results,
@@ -110,6 +113,7 @@ async def continue_conversation(
 
         hierarchical_results = recent_context.results[:5]  # Limit to top 5 recent items
 
+        hierarchical_results_for_count = hierarchical_results
         template_context = {
             "topic": f"Recent Activity from ({request.timeframe})",
             "timeframe": request.timeframe,
@@ -129,9 +133,6 @@ async def continue_conversation(
         relation_count = 0
         entity_count = 0
 
-        # Get the hierarchical results from the template context
-        hierarchical_results_for_count = template_context.get("hierarchical_results", [])
-
         # For topic-based search
         if request.topic:
             for item in hierarchical_results_for_count:
@@ -159,29 +160,24 @@ async def continue_conversation(
                             elif related.type == "entity":  # pragma: no cover
                                 entity_count += 1  # pragma: no cover
 
-        # Build metadata
-        metadata = {
-            "query": request.topic,
-            "timeframe": request.timeframe,
-            "search_count": len(search_results)
-            if request.topic
-            else 0,  # Original search results count
-            "context_count": len(hierarchical_results_for_count),
-            "observation_count": observation_count,
-            "relation_count": relation_count,
-            "total_items": (
+        prompt_metadata = PromptMetadata(
+            query=request.topic,
+            timeframe=request.timeframe,
+            search_count=len(search_results) if request.topic else 0,
+            context_count=len(hierarchical_results_for_count),
+            observation_count=observation_count,
+            relation_count=relation_count,
+            total_items=(
                 len(hierarchical_results_for_count)
                 + observation_count
                 + relation_count
                 + entity_count
             ),
-            "search_limit": request.search_items_limit,
-            "context_depth": request.depth,
-            "related_limit": request.related_items_limit,
-            "generated_at": datetime.now(timezone.utc).isoformat(),
-        }
-
-        prompt_metadata = PromptMetadata(**metadata)
+            search_limit=request.search_items_limit,
+            context_depth=request.depth,
+            related_limit=request.related_items_limit,
+            generated_at=datetime.now(timezone.utc).isoformat(),
+        )
 
         return PromptResponse(
             prompt=rendered_prompt, context=template_context, metadata=prompt_metadata
@@ -229,7 +225,7 @@ async def search_prompt(
     results = await search_service.search(query, limit=limit, offset=offset)
     search_results = await to_search_results(entity_service, results)
 
-    template_context = {
+    template_context: dict[str, Any] = {
         "query": request.query,
         "timeframe": request.timeframe,
         "results": search_results,
@@ -241,22 +237,19 @@ async def search_prompt(
         # Render template
         rendered_prompt = await template_loader.render("prompts/search.hbs", template_context)
 
-        # Build metadata
-        metadata = {
-            "query": request.query,
-            "timeframe": request.timeframe,
-            "search_count": len(search_results),
-            "context_count": len(search_results),
-            "observation_count": 0,  # Search results don't include observations
-            "relation_count": 0,  # Search results don't include relations
-            "total_items": len(search_results),
-            "search_limit": limit,
-            "context_depth": 0,  # No context depth for basic search
-            "related_limit": 0,  # No related items for basic search
-            "generated_at": datetime.now(timezone.utc).isoformat(),
-        }
-
-        prompt_metadata = PromptMetadata(**metadata)
+        prompt_metadata = PromptMetadata(
+            query=request.query,
+            timeframe=request.timeframe,
+            search_count=len(search_results),
+            context_count=len(search_results),
+            observation_count=0,
+            relation_count=0,
+            total_items=len(search_results),
+            search_limit=limit,
+            context_depth=0,
+            related_limit=0,
+            generated_at=datetime.now(timezone.utc).isoformat(),
+        )
 
         return PromptResponse(
             prompt=rendered_prompt, context=template_context, metadata=prompt_metadata

src/basic_memory/api/v2/routers/resource_router.py

@@ -211,7 +211,7 @@ async def create_resource(
                 action="create",
                 phase="search_index",
             ):
-                await search_service.index_entity(entity)  # pyright: ignore
+                await search_service.index_entity(entity)
 
             return ResourceResponse(
                 entity_id=entity.id,
@@ -326,6 +326,8 @@ async def update_resource(
                         "updated_at": file_metadata.modified_at,
                     },
                 )
+            if updated_entity is None:
+                raise HTTPException(status_code=404, detail=f"Entity {entity_id} not found")
 
             with telemetry.scope(
                 "api.resource.update.search_index",
@@ -333,7 +335,7 @@ async def update_resource(
                 action="update",
                 phase="search_index",
             ):
-                await search_service.index_entity(updated_entity)  # pyright: ignore
+                await search_service.index_entity(updated_entity)
 
             return ResourceResponse(
                 entity_id=entity.id,

src/basic_memory/api/v2/utils.py

@@ -1,8 +1,6 @@
-from typing import Optional, List
+from typing import Any, Protocol, Optional, List, Sequence
 
 from basic_memory import telemetry
-from basic_memory.models import Entity as EntityModel
-from basic_memory.repository import EntityRepository
 from basic_memory.repository.search_repository import SearchIndexRow
 from basic_memory.schemas.memory import (
     EntitySummary,
@@ -13,19 +11,38 @@ from basic_memory.schemas.memory import (
     ContextResult,
 )
 from basic_memory.schemas.search import SearchItemType, SearchResult
-from basic_memory.services import EntityService
 from basic_memory.services.context_service import (
     ContextResultRow,
     ContextResult as ServiceContextResult,
 )
 
 
+class EntityBatchLookup(Protocol):
+    async def find_by_ids(self, ids: List[int]) -> Sequence[Any]: ...
+
+
+class EntityServiceBatchLookup(Protocol):
+    async def get_entities_by_id(self, ids: List[int]) -> Sequence[Any]: ...
+
+
+def _required_str(value: str | None, field_name: str) -> str:
+    """Return a required search field or fail before producing invalid response data."""
+    if value is None:
+        raise ValueError(f"Search result is missing required field: {field_name}")
+    return value
+
+
+def _search_item_type(value: str | SearchItemType) -> SearchItemType:
+    """Normalize repository row type strings into the public search enum."""
+    return value if isinstance(value, SearchItemType) else SearchItemType(value)
+
+
 async def to_graph_context(
     context_result: ServiceContextResult,
-    entity_repository: EntityRepository,
+    entity_repository: EntityBatchLookup,
     page: Optional[int] = None,
     page_size: Optional[int] = None,
-):
+) -> GraphContext:
     with telemetry.scope(
         "memory.hydrate_context",
         domain="memory",
@@ -44,17 +61,18 @@ async def to_graph_context(
                 + context_item.observations
                 + context_item.related_results
             ):
-                if item.type == SearchItemType.ENTITY:
+                item_type = _search_item_type(item.type)
+                if item_type == SearchItemType.ENTITY:
                     # Entity's own ID for its external_id
                     entity_ids_needed.add(item.id)
-                elif item.type == SearchItemType.OBSERVATION:
+                elif item_type == SearchItemType.OBSERVATION:
                     # Parent entity ID for entity_external_id
-                    if item.entity_id:  # pyright: ignore
-                        entity_ids_needed.add(item.entity_id)  # pyright: ignore
-                elif item.type == SearchItemType.RELATION:
+                    if item.entity_id:
+                        entity_ids_needed.add(item.entity_id)
+                elif item_type == SearchItemType.RELATION:
                     # Source and target entity IDs for external_ids
-                    if item.from_id:  # pyright: ignore
-                        entity_ids_needed.add(item.from_id)  # pyright: ignore
+                    if item.from_id:
+                        entity_ids_needed.add(item.from_id)
                     if item.to_id:
                         entity_ids_needed.add(item.to_id)
 
@@ -75,57 +93,60 @@ async def to_graph_context(
                 entity_external_id_lookup[e.id] = e.external_id
 
         # Helper function to convert items to summaries
-        def to_summary(item: SearchIndexRow | ContextResultRow):
-            match item.type:
+        def to_summary(
+            item: SearchIndexRow | ContextResultRow,
+        ) -> EntitySummary | ObservationSummary | RelationSummary:
+            item_type = _search_item_type(item.type)
+            match item_type:
                 case SearchItemType.ENTITY:
                     return EntitySummary(
                         external_id=entity_external_id_lookup.get(item.id, ""),
                         entity_id=item.id,
-                        title=item.title,  # pyright: ignore
+                        title=_required_str(item.title, "title"),
                         permalink=item.permalink,
                         content=item.content,
-                        file_path=item.file_path,
+                        file_path=_required_str(item.file_path, "file_path"),
                         created_at=item.created_at,
                     )
                 case SearchItemType.OBSERVATION:
                     entity_ext_id = None
-                    if item.entity_id:  # pyright: ignore
-                        entity_ext_id = entity_external_id_lookup.get(item.entity_id)  # pyright: ignore
+                    entity_title = None
+                    if item.entity_id:
+                        entity_ext_id = entity_external_id_lookup.get(item.entity_id)
+                        entity_title = entity_title_lookup.get(item.entity_id)
                     return ObservationSummary(
                         observation_id=item.id,
-                        entity_id=item.entity_id,  # pyright: ignore
+                        entity_id=item.entity_id,
                         entity_external_id=entity_ext_id,
-                        title=entity_title_lookup.get(item.entity_id),  # pyright: ignore
-                        file_path=item.file_path,
-                        category=item.category,  # pyright: ignore
-                        content=item.content,  # pyright: ignore
-                        permalink=item.permalink,  # pyright: ignore
+                        title=entity_title,
+                        file_path=_required_str(item.file_path, "file_path"),
+                        category=_required_str(item.category, "category"),
+                        content=_required_str(item.content, "content"),
+                        permalink=_required_str(item.permalink, "permalink"),
                         created_at=item.created_at,
                     )
                 case SearchItemType.RELATION:
-                    from_title = entity_title_lookup.get(item.from_id) if item.from_id else None  # pyright: ignore
+                    from_title = entity_title_lookup.get(item.from_id) if item.from_id else None
                     to_title = entity_title_lookup.get(item.to_id) if item.to_id else None
                     from_ext_id = (
                         entity_external_id_lookup.get(item.from_id) if item.from_id else None
-                    )  # pyright: ignore
+                    )
                     to_ext_id = entity_external_id_lookup.get(item.to_id) if item.to_id else None
                     return RelationSummary(
                         relation_id=item.id,
-                        entity_id=item.entity_id,  # pyright: ignore
-                        title=item.title,  # pyright: ignore
-                        file_path=item.file_path,
-                        permalink=item.permalink,  # pyright: ignore
-                        relation_type=item.relation_type,  # pyright: ignore
+                        entity_id=item.entity_id,
+                        title=_required_str(item.title, "title"),
+                        file_path=_required_str(item.file_path, "file_path"),
+                        permalink=_required_str(item.permalink, "permalink"),
+                        relation_type=_required_str(item.relation_type, "relation_type"),
                         from_entity=from_title,
-                        from_entity_id=item.from_id,  # pyright: ignore
+                        from_entity_id=item.from_id,
                         from_entity_external_id=from_ext_id,
                         to_entity=to_title,
                         to_entity_id=item.to_id,
                         to_entity_external_id=to_ext_id,
                         created_at=item.created_at,
                     )
-                case _:  # pragma: no cover
-                    raise ValueError(f"Unexpected type: {item.type}")
 
         with telemetry.scope(
             "memory.hydrate_context.shape_results",
@@ -137,12 +158,16 @@ async def to_graph_context(
             hierarchical_results = []
             for context_item in context_result.results:
                 primary_result = to_summary(context_item.primary_result)
-                observations = [to_summary(obs) for obs in context_item.observations]
+                observations = [
+                    summary
+                    for summary in (to_summary(obs) for obs in context_item.observations)
+                    if isinstance(summary, ObservationSummary)
+                ]
                 related = [to_summary(rel) for rel in context_item.related_results]
                 hierarchical_results.append(
                     ContextResult(
                         primary_result=primary_result,
-                        observations=observations,  # pyright: ignore[reportArgumentType]
+                        observations=observations,
                         related_results=related,
                     )
                 )
@@ -170,7 +195,9 @@ async def to_graph_context(
         )
 
 
-async def to_search_results(entity_service: EntityService, results: List[SearchIndexRow]):
+async def to_search_results(
+    entity_service: EntityServiceBatchLookup, results: List[SearchIndexRow]
+) -> list[SearchResult]:
     with telemetry.scope(
         "search.hydrate_results",
         domain="search",
@@ -187,7 +214,7 @@ async def to_search_results(entity_service: EntityService, results: List[SearchI
                     all_entity_ids.add(eid)
 
         # Single batch fetch for all entities
-        entities_by_id: dict[int, EntityModel] = {}
+        entities_by_id: dict[int, Any] = {}
         with telemetry.scope(
             "search.hydrate_results.fetch_entities",
             domain="search",
@@ -222,20 +249,20 @@ async def to_search_results(entity_service: EntityService, results: List[SearchI
                     entity_id = result.entity_id
 
                 # Look up entities by their specific IDs
-                parent_entity = entities_by_id.get(result.entity_id) if result.entity_id else None  # pyright: ignore
-                from_entity = entities_by_id.get(result.from_id) if result.from_id else None  # pyright: ignore
+                parent_entity = entities_by_id.get(result.entity_id) if result.entity_id else None
+                from_entity = entities_by_id.get(result.from_id) if result.from_id else None
                 to_entity = entities_by_id.get(result.to_id) if result.to_id else None
 
                 search_results.append(
                     SearchResult(
-                        title=result.title,  # pyright: ignore
-                        type=result.type,  # pyright: ignore
+                        title=_required_str(result.title, "title"),
+                        type=_search_item_type(result.type),
                         permalink=result.permalink,
-                        score=result.score,  # pyright: ignore
+                        score=result.score if result.score is not None else 0.0,
                         entity=parent_entity.permalink if parent_entity else None,
                         content=result.content,
                         matched_chunk=result.matched_chunk_text,
-                        file_path=result.file_path,
+                        file_path=_required_str(result.file_path, "file_path"),
                         metadata=result.metadata,
                         entity_id=entity_id,
                         observation_id=observation_id,

src/basic_memory/cli/auto_update.py

@@ -22,7 +22,7 @@ PACKAGE_NAME = "basic-memory"
 PYPI_JSON_URL = "https://pypi.org/pypi/basic-memory/json"
 
 PYPI_TIMEOUT_SECONDS = 5
-BREW_OUTDATED_TIMEOUT_SECONDS = 15
+BREW_OUTDATED_TIMEOUT_SECONDS = 60
 UV_UPGRADE_TIMEOUT_SECONDS = 180
 BREW_UPGRADE_TIMEOUT_SECONDS = 600
 

src/basic_memory/cli/commands/cloud/api_client.py

@@ -99,41 +99,39 @@ async def make_api_request(
             response = await client.request(method=method, url=url, headers=headers, json=json_data)
             response.raise_for_status()
             return response
+        except httpx.HTTPStatusError as e:
+            response = e.response
+
+            # Try to parse error detail from response
+            error_detail = None
+            try:
+                error_detail = response.json()
+            except Exception:
+                # If JSON parsing fails, we'll handle it as a generic error
+                pass
+
+            # Check for subscription_required error (403)
+            if response.status_code == 403 and isinstance(error_detail, dict):
+                # Handle both FastAPI HTTPException format (nested under "detail")
+                # and direct format
+                detail_obj = error_detail.get("detail", error_detail)
+                if (
+                    isinstance(detail_obj, dict)
+                    and detail_obj.get("error") == "subscription_required"
+                ):
+                    message = detail_obj.get("message", "Active subscription required")
+                    subscribe_url = detail_obj.get(
+                        "subscribe_url", "https://basicmemory.com/subscribe"
+                    )
+                    raise SubscriptionRequiredError(
+                        message=message, subscribe_url=subscribe_url
+                    ) from e
+
+            # Raise generic CloudAPIError with status code and detail
+            raise CloudAPIError(
+                f"API request failed: {e}",
+                status_code=response.status_code,
+                detail=error_detail if isinstance(error_detail, dict) else {},
+            ) from e
         except httpx.HTTPError as e:
-            # Check if this is a response error with response details
-            if hasattr(e, "response") and e.response is not None:  # pyright: ignore [reportAttributeAccessIssue]
-                response = e.response  # type: ignore
-
-                # Try to parse error detail from response
-                error_detail = None
-                try:
-                    error_detail = response.json()
-                except Exception:
-                    # If JSON parsing fails, we'll handle it as a generic error
-                    pass
-
-                # Check for subscription_required error (403)
-                if response.status_code == 403 and isinstance(error_detail, dict):
-                    # Handle both FastAPI HTTPException format (nested under "detail")
-                    # and direct format
-                    detail_obj = error_detail.get("detail", error_detail)
-                    if (
-                        isinstance(detail_obj, dict)
-                        and detail_obj.get("error") == "subscription_required"
-                    ):
-                        message = detail_obj.get("message", "Active subscription required")
-                        subscribe_url = detail_obj.get(
-                            "subscribe_url", "https://basicmemory.com/subscribe"
-                        )
-                        raise SubscriptionRequiredError(
-                            message=message, subscribe_url=subscribe_url
-                        ) from e
-
-                # Raise generic CloudAPIError with status code and detail
-                raise CloudAPIError(
-                    f"API request failed: {e}",
-                    status_code=response.status_code,
-                    detail=error_detail if isinstance(error_detail, dict) else {},
-                ) from e
-
             raise CloudAPIError(f"API request failed: {e}") from e

src/basic_memory/cli/commands/cloud/cloud_utils.py

@@ -41,6 +41,10 @@ async def fetch_cloud_projects(
 ) -> CloudProjectList:
     """Fetch list of projects from cloud API.
 
+    Args:
+        project_name: Optional project name for workspace resolution
+        workspace: Cloud workspace tenant_id to list projects from
+
     Returns:
         CloudProjectList with projects from cloud
     """
@@ -112,12 +116,12 @@ async def sync_project(project_name: str, force_full: bool = False) -> None:
 
     Args:
         project_name: Name of project to sync
-        force_full: If True, force a full scan bypassing watermark optimization
+        force_full: ignored, kept for backwards compatibility
     """
     try:
         from basic_memory.cli.commands.command_utils import run_sync
 
-        await run_sync(project=project_name, force_full=force_full)
+        await run_sync(project=project_name)
     except Exception as e:
         raise CloudUtilsError(f"Failed to sync project '{project_name}': {e}") from e
 

src/basic_memory/cli/commands/cloud/project_sync.py

@@ -124,22 +124,6 @@ def sync_project_command(
 
         if success:
             console.print(f"[green]{name} synced successfully[/green]")
-
-            # Trigger database sync if not a dry run
-            if not dry_run:
-
-                async def _trigger_db_sync():
-                    async with get_client(project_name=name) as client:
-                        return await ProjectClient(client).sync(
-                            project_data.external_id, force_full=False
-                        )
-
-                try:
-                    with force_routing(cloud=True):
-                        result = run_with_cleanup(_trigger_db_sync())
-                    console.print(f"[dim]Database sync initiated: {result.get('message')}[/dim]")
-                except Exception as e:
-                    console.print(f"[yellow]Warning: Could not trigger database sync: {e}[/yellow]")
         else:
             console.print(f"[red]{name} sync failed[/red]")
             raise typer.Exit(1)
@@ -202,22 +186,6 @@ def bisync_project_command(
             sync_entry.last_sync = datetime.now()
             sync_entry.bisync_initialized = True
             ConfigManager().save_config(config)
-
-            # Trigger database sync if not a dry run
-            if not dry_run:
-
-                async def _trigger_db_sync():
-                    async with get_client(project_name=name) as client:
-                        return await ProjectClient(client).sync(
-                            project_data.external_id, force_full=False
-                        )
-
-                try:
-                    with force_routing(cloud=True):
-                        result = run_with_cleanup(_trigger_db_sync())
-                    console.print(f"[dim]Database sync initiated: {result.get('message')}[/dim]")
-                except Exception as e:
-                    console.print(f"[yellow]Warning: Could not trigger database sync: {e}[/yellow]")
         else:
             console.print(f"[red]{name} bisync failed[/red]")
             raise typer.Exit(1)

src/basic_memory/cli/commands/cloud/upload_command.py

@@ -106,6 +106,8 @@ def upload(
                 raise typer.Exit(1)
 
         # Perform upload (or dry run)
+        if resolved_workspace:
+            console.print(f"[dim]Using workspace: {resolved_workspace}[/dim]")
         if dry_run:
             console.print(
                 f"[yellow]DRY RUN: Showing what would be uploaded to '{project}'[/yellow]"
@@ -140,7 +142,7 @@ def upload(
         if sync and not dry_run:
             console.print(f"[blue]Syncing project '{project}'...[/blue]")
             try:
-                await sync_project(project, force_full=True)
+                await sync_project(project)
             except Exception as e:
                 console.print(f"[yellow]Warning: Sync failed: {e}[/yellow]")
                 console.print("[dim]Files uploaded but may not be indexed yet[/dim]")

src/basic_memory/cli/commands/db.py

@@ -1,5 +1,6 @@
 """Database management commands."""
 
+from dataclasses import dataclass
 from pathlib import Path
 
 import typer
@@ -12,6 +13,7 @@ from basic_memory import db
 from basic_memory.cli.app import app
 from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.config import ConfigManager, ProjectMode
+from basic_memory.indexing import IndexProgress
 from basic_memory.repository import ProjectRepository
 from basic_memory.services.initialization import reconcile_projects_with_config
 from basic_memory.sync.sync_service import get_sync_service
@@ -19,6 +21,39 @@ from basic_memory.sync.sync_service import get_sync_service
 console = Console()
 
 
+@dataclass(slots=True)
+class EmbeddingProgress:
+    """Typed CLI progress payload for embedding backfills."""
+
+    entity_id: int
+    completed: int
+    total: int
+
+
+def _format_eta(seconds: float | None) -> str:
+    """Render a compact ETA string for CLI progress descriptions."""
+    if seconds is None:
+        return "--:--"
+
+    whole_seconds = max(int(seconds), 0)
+    minutes, remaining_seconds = divmod(whole_seconds, 60)
+    hours, remaining_minutes = divmod(minutes, 60)
+    if hours:
+        return f"{hours:d}:{remaining_minutes:02d}:{remaining_seconds:02d}"
+    return f"{remaining_minutes:02d}:{remaining_seconds:02d}"
+
+
+def _format_index_progress(progress: IndexProgress) -> str:
+    """Render typed index progress as a compact Rich task description."""
+    files_per_minute = int(progress.files_per_minute) if progress.files_per_minute else 0
+    return (
+        "  Indexing files... "
+        f"{progress.files_processed}/{progress.files_total} files | "
+        f"{progress.batches_completed}/{progress.batches_total} batches | "
+        f"{files_per_minute}/min | ETA {_format_eta(progress.eta_seconds)}"
+    )
+
+
 async def _reindex_projects(app_config):
     """Reindex all projects in a single async context.
 
@@ -112,20 +147,30 @@ def reindex(
         False, "--embeddings", "-e", help="Rebuild vector embeddings (requires semantic search)"
     ),
     search: bool = typer.Option(False, "--search", "-s", help="Rebuild full-text search index"),
+    full: bool = typer.Option(
+        False,
+        "--full",
+        help="Force a full filesystem scan and file reindex instead of the default incremental scan",
+    ),
     project: str = typer.Option(
         None, "--project", "-p", help="Reindex a specific project (default: all)"
     ),
 ):  # pragma: no cover
     """Rebuild search indexes and/or vector embeddings without dropping the database.
 
-    By default rebuilds everything (search + embeddings if semantic is enabled).
-    Use --search or --embeddings to rebuild only one.
+    By default runs incremental search + embeddings (if semantic search is enabled).
+    Use --full to bypass incremental scan optimization, rebuild all file-backed search rows,
+    and re-embed all eligible notes.
+    Use --search or --embeddings to rebuild only one side.
 
     Examples:
-        bm reindex                  # Rebuild everything
+        bm reindex                  # Incremental search + embeddings
+        bm reindex --full           # Full search + full re-embed
         bm reindex --embeddings     # Only rebuild vector embeddings
         bm reindex --search         # Only rebuild FTS index
-        bm reindex -p claw          # Reindex only the 'claw' project
+        bm reindex --full --search  # Full search only
+        bm reindex --full --embeddings  # Full re-embed only
+        bm reindex -p claw --full   # Full reindex for only the 'claw' project
     """
     # If neither flag is set, do both
     if not embeddings and not search:
@@ -144,10 +189,19 @@ def reindex(
         if not search:
             raise typer.Exit(0)
 
-    run_with_cleanup(_reindex(app_config, search=search, embeddings=embeddings, project=project))
+    run_with_cleanup(
+        _reindex(app_config, search=search, embeddings=embeddings, full=full, project=project)
+    )
 
 
-async def _reindex(app_config, search: bool, embeddings: bool, project: str | None):
+async def _reindex(
+    app_config,
+    *,
+    search: bool,
+    embeddings: bool,
+    full: bool,
+    project: str | None,
+):
     """Run reindex operations."""
     from basic_memory.repository import EntityRepository
     from basic_memory.repository.search_repository import create_search_repository
@@ -185,14 +239,47 @@ async def _reindex(app_config, search: bool, embeddings: bool, project: str | No
             console.print(f"\n[bold]Project: [cyan]{proj.name}[/cyan][/bold]")
 
             if search:
-                console.print("  Rebuilding full-text search index...")
+                search_mode_label = "full scan" if full else "incremental scan"
+                console.print(
+                    f"  Rebuilding full-text search index ([cyan]{search_mode_label}[/cyan])..."
+                )
                 sync_service = await get_sync_service(proj)
                 sync_dir = Path(proj.path)
-                await sync_service.sync(sync_dir, project_name=proj.name)
-                console.print("  [green]✓[/green] Full-text search index rebuilt")
+                with Progress(
+                    SpinnerColumn(),
+                    TextColumn("[progress.description]{task.description}"),
+                    BarColumn(),
+                    TaskProgressColumn(),
+                    console=console,
+                ) as progress:
+                    task = progress.add_task("  Indexing files... scanning changes", total=1)
+
+                    async def on_index_progress(update: IndexProgress) -> None:
+                        total = update.files_total or 1
+                        completed = update.files_processed if update.files_total else 1
+                        progress.update(
+                            task,
+                            description=_format_index_progress(update),
+                            total=total,
+                            completed=min(completed, total),
+                        )
+
+                    await sync_service.sync(
+                        sync_dir,
+                        project_name=proj.name,
+                        force_full=full,
+                        sync_embeddings=False,
+                        progress_callback=on_index_progress,
+                    )
+                    progress.update(task, completed=progress.tasks[task].total or 1)
+
+                console.print("  [green]done[/green] Full-text search index rebuilt")
 
             if embeddings:
-                console.print("  Building vector embeddings...")
+                embedding_mode_label = "full rebuild" if full else "incremental sync"
+                console.print(
+                    f"  Building vector embeddings ([cyan]{embedding_mode_label}[/cyan])..."
+                )
                 entity_repository = EntityRepository(session_maker, project_id=proj.id)
                 search_repository = create_search_repository(
                     session_maker, project_id=proj.id, app_config=app_config
@@ -213,13 +300,29 @@ async def _reindex(app_config, search: bool, embeddings: bool, project: str | No
                     task = progress.add_task("  Embedding entities...", total=None)
 
                     def on_progress(entity_id, index, total):
-                        progress.update(task, total=total, completed=index)
+                        embedding_progress = EmbeddingProgress(
+                            entity_id=entity_id,
+                            completed=index,
+                            total=total,
+                        )
+                        # Trigger: repository progress now reports terminal entity completion.
+                        # Why: operators need to see finished embedding work rather than
+                        # entities merely entering prepare.
+                        # Outcome: the CLI bar advances steadily with real completed work.
+                        progress.update(
+                            task,
+                            total=embedding_progress.total,
+                            completed=embedding_progress.completed,
+                        )
 
-                    stats = await search_service.reindex_vectors(progress_callback=on_progress)
+                    stats = await search_service.reindex_vectors(
+                        progress_callback=on_progress,
+                        force_full=full,
+                    )
                     progress.update(task, completed=stats["total_entities"])
 
                 console.print(
-                    f"  [green]✓[/green] Embeddings complete: "
+                    f"  [green]done[/green] Embeddings complete: "
                     f"{stats['embedded']} entities embedded, "
                     f"{stats['skipped']} skipped, "
                     f"{stats['errors']} errors"

src/basic_memory/cli/commands/doctor.py

@@ -101,7 +101,7 @@ async def run_doctor() -> None:
                 console.print("[green]OK[/green] Manual file written")
 
                 sync_data = await project_client.sync(
-                    project_id, force_full=True, run_in_background=False
+                    project_id, force_full=False, run_in_background=False
                 )
                 sync_report = SyncReportResponse.model_validate(sync_data)
                 if sync_report.total == 0:

src/basic_memory/cli/commands/project.py

@@ -14,6 +14,7 @@ from rich.text import Text
 
 from basic_memory.cli.app import app
 from basic_memory.cli.auth import CLIAuth
+from basic_memory.cli.commands.cloud.api_client import CloudAPIError, make_api_request
 from basic_memory.cli.commands.cloud.bisync_commands import get_mount_info
 from basic_memory.cli.commands.cloud.project_sync import (
     _has_cloud_credentials,
@@ -26,9 +27,13 @@ from basic_memory.cli.commands.cloud.rclone_commands import (
 from basic_memory.cli.commands.command_utils import get_project_info, run_with_cleanup
 from basic_memory.cli.commands.routing import force_routing, validate_routing_flags
 from basic_memory.config import ConfigManager, ProjectEntry, ProjectMode
-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import get_client, resolve_configured_workspace
 from basic_memory.mcp.clients import ProjectClient
-from basic_memory.schemas.cloud import ProjectVisibility
+from basic_memory.schemas.cloud import (
+    CloudProjectIndexStatus,
+    CloudTenantIndexStatusResponse,
+    ProjectVisibility,
+)
 from basic_memory.schemas.project_info import ProjectItem, ProjectList
 from basic_memory.utils import generate_permalink, normalize_project_path
 
@@ -58,6 +63,211 @@ def make_bar(value: int, max_value: int, width: int = 40) -> Text:
     return bar
 
 
+def _uses_cloud_project_info_route(project_name: str, *, local: bool, cloud: bool) -> bool:
+    """Return whether project info should attempt cloud augmentation."""
+    if local:
+        return False
+    if cloud:
+        return True
+
+    config_manager = ConfigManager()
+    resolved_name, _ = config_manager.get_project(project_name)
+    effective_name = resolved_name or project_name
+    return config_manager.config.get_project_mode(effective_name) == ProjectMode.CLOUD
+
+
+def _resolve_cloud_status_workspace_id(project_name: str) -> str:
+    """Resolve the tenant/workspace for cloud index status lookup."""
+    config_manager = ConfigManager()
+    config = config_manager.config
+
+    if not _has_cloud_credentials(config):
+        raise RuntimeError(
+            "Cloud credentials not found. Run `bm cloud api-key save <key>` or `bm cloud login` first."
+        )
+
+    configured_name, _ = config_manager.get_project(project_name)
+    effective_name = configured_name or project_name
+
+    workspace_id = resolve_configured_workspace(config=config, project_name=effective_name)
+    if workspace_id is not None:
+        return workspace_id
+
+    workspace_id = _resolve_workspace_id(config, None)
+    if workspace_id is not None:
+        return workspace_id
+
+    raise RuntimeError(
+        f"Cloud workspace could not be resolved for project '{effective_name}'. "
+        "Set a project workspace with `bm project set-cloud --workspace ...` or configure a "
+        "default workspace with `bm cloud workspace set-default ...`."
+    )
+
+
+async def _resolve_cloud_status_workspace_id_async(project_name: str) -> str:
+    """Resolve the tenant/workspace for cloud index status lookup in async contexts."""
+    config_manager = ConfigManager()
+    config = config_manager.config
+
+    if not _has_cloud_credentials(config):
+        raise RuntimeError(
+            "Cloud credentials not found. Run `bm cloud api-key save <key>` or `bm cloud login` first."
+        )
+
+    configured_name, _ = config_manager.get_project(project_name)
+    effective_name = configured_name or project_name
+
+    workspace_id = resolve_configured_workspace(config=config, project_name=effective_name)
+    if workspace_id is not None:
+        return workspace_id
+
+    from basic_memory.mcp.project_context import get_available_workspaces
+
+    workspaces = await get_available_workspaces()
+    if len(workspaces) == 1:
+        return workspaces[0].tenant_id
+
+    raise RuntimeError(
+        f"Cloud workspace could not be resolved for project '{effective_name}'. "
+        "Set a project workspace with `bm project set-cloud --workspace ...` or configure a "
+        "default workspace with `bm cloud workspace set-default ...`."
+    )
+
+
+def _match_cloud_index_status_project(
+    project_name: str, projects: list[CloudProjectIndexStatus]
+) -> CloudProjectIndexStatus | None:
+    """Match the requested project against the tenant index-status payload."""
+    exact_match = next(
+        (project for project in projects if project.project_name == project_name), None
+    )
+    if exact_match is not None:
+        return exact_match
+
+    project_permalink = generate_permalink(project_name)
+    permalink_matches = [
+        project
+        for project in projects
+        if generate_permalink(project.project_name) == project_permalink
+    ]
+    if len(permalink_matches) == 1:
+        return permalink_matches[0]
+
+    return None
+
+
+def _format_cloud_index_status_error(error: Exception) -> str:
+    """Convert cloud lookup failures into concise user-facing text."""
+    if isinstance(error, CloudAPIError):
+        detail_message: str | None = None
+        detail = error.detail.get("detail")
+        if isinstance(detail, str):
+            detail_message = detail
+        elif isinstance(detail, dict):
+            if isinstance(detail.get("message"), str):
+                detail_message = detail["message"]
+            elif isinstance(detail.get("detail"), str):
+                detail_message = detail["detail"]
+
+        if error.status_code and detail_message:
+            return f"HTTP {error.status_code}: {detail_message}"
+        if error.status_code:
+            return f"HTTP {error.status_code}"
+
+    return str(error)
+
+
+async def _fetch_cloud_project_index_status(project_name: str) -> CloudProjectIndexStatus:
+    """Fetch cloud index freshness for one project from the admin tenant endpoint."""
+    workspace_id = await _resolve_cloud_status_workspace_id_async(project_name)
+    host_url = ConfigManager().config.cloud_host.rstrip("/")
+
+    try:
+        response = await make_api_request(
+            method="GET",
+            url=f"{host_url}/admin/tenants/{workspace_id}/index-status",
+        )
+    except typer.Exit as exc:
+        if exc.exit_code not in (None, 0):
+            raise RuntimeError(
+                "Cloud credentials not found. Run `bm cloud api-key save <key>` or "
+                "`bm cloud login` first."
+            ) from exc
+        raise
+
+    tenant_status = CloudTenantIndexStatusResponse.model_validate(response.json())
+    if tenant_status.error:
+        raise RuntimeError(tenant_status.error)
+
+    project_status = _match_cloud_index_status_project(project_name, tenant_status.projects)
+    if project_status is None:
+        raise RuntimeError(
+            f"Project '{project_name}' was not found in workspace index status "
+            f"for tenant '{workspace_id}'."
+        )
+
+    return project_status
+
+
+def _load_cloud_project_index_status(
+    project_name: str,
+) -> tuple[CloudProjectIndexStatus | None, str | None]:
+    """Best-effort wrapper around the cloud index freshness lookup."""
+    try:
+        return run_with_cleanup(_fetch_cloud_project_index_status(project_name)), None
+    except Exception as exc:
+        return None, _format_cloud_index_status_error(exc)
+
+
+def _build_cloud_index_status_section(
+    cloud_index_status: CloudProjectIndexStatus | None,
+    cloud_index_status_error: str | None,
+) -> Table | None:
+    """Render the optional Cloud Index Status block for rich project info."""
+    if cloud_index_status is None and cloud_index_status_error is None:
+        return None
+
+    table = Table.grid(padding=(0, 2))
+    table.add_column("property", style="cyan")
+    table.add_column("value", style="green")
+
+    table.add_row("[bold]Cloud Index Status[/bold]", "")
+
+    if cloud_index_status_error is not None:
+        table.add_row("[yellow]●[/yellow] Warning", f"[yellow]{cloud_index_status_error}[/yellow]")
+        return table
+
+    if cloud_index_status is None:
+        return table
+
+    table.add_row("Files", str(cloud_index_status.current_file_count))
+    table.add_row(
+        "Note content",
+        f"{cloud_index_status.note_content_synced}/{cloud_index_status.current_file_count}",
+    )
+    table.add_row(
+        "Search",
+        f"{cloud_index_status.total_indexed_entities}/{cloud_index_status.current_file_count}",
+    )
+    table.add_row("Embeddable", str(cloud_index_status.embeddable_indexed_entities))
+    table.add_row(
+        "Vectorized",
+        (
+            f"{cloud_index_status.total_entities_with_chunks}/"
+            f"{cloud_index_status.embeddable_indexed_entities}"
+        ),
+    )
+
+    if cloud_index_status.reindex_recommended:
+        table.add_row("[yellow]●[/yellow] Status", "[yellow]Reindex recommended[/yellow]")
+        if cloud_index_status.reindex_reason:
+            table.add_row("Reason", f"[yellow]{cloud_index_status.reindex_reason}[/yellow]")
+    else:
+        table.add_row("[green]●[/green] Status", "[green]Up to date[/green]")
+
+    return table
+
+
 def _normalize_project_visibility(visibility: str | None) -> ProjectVisibility:
     """Normalize CLI visibility input to the cloud API contract."""
     if visibility is None:
@@ -253,6 +463,12 @@ def list_projects(
             if cloud_project is not None and cloud_ws_name:
                 ws_label = f"{cloud_ws_name} ({cloud_ws_type})" if cloud_ws_type else cloud_ws_name
 
+            # display_name is a human label for private UUID-named projects (e.g., "My Project").
+            # Keep "name" as the canonical identifier for scripting/JSON consumers;
+            # the Rich table uses display_name when available.
+            display_name = (
+                cloud_project.display_name if cloud_project and cloud_project.display_name else None
+            )
             row_data = {
                 "name": project_name,
                 "permalink": permalink,
@@ -263,6 +479,8 @@ def list_projects(
                 "sync": has_sync,
                 "is_default": is_default,
             }
+            if display_name:
+                row_data["display_name"] = display_name
             if ws_label:
                 row_data["workspace"] = cloud_ws_name or ""
                 if cloud_ws_type:
@@ -278,7 +496,7 @@ def list_projects(
         # --- Rich table output ---
         for row_data in project_rows:
             table.add_row(
-                row_data["name"],
+                row_data.get("display_name") or row_data["name"],
                 row_data["local_path"],
                 row_data["cloud_path"],
                 row_data.get("workspace", "")
@@ -848,9 +1066,20 @@ def display_project_info(
         with force_routing(local=local, cloud=cloud):
             info = run_with_cleanup(get_project_info(name))
 
+        cloud_index_status: CloudProjectIndexStatus | None = None
+        cloud_index_status_error: str | None = None
+        if _uses_cloud_project_info_route(info.project_name, local=local, cloud=cloud):
+            cloud_index_status, cloud_index_status_error = _load_cloud_project_index_status(
+                info.project_name
+            )
+
         if json_output:
-            # Convert to JSON and print
-            print(json.dumps(info.model_dump(), indent=2, default=str))
+            output = info.model_dump()
+            output["cloud_index_status"] = (
+                cloud_index_status.model_dump() if cloud_index_status is not None else None
+            )
+            output["cloud_index_status_error"] = cloud_index_status_error
+            print(json.dumps(output, indent=2, default=str))
         else:
             # --- Left column: Knowledge Graph stats ---
             left = Table.grid(padding=(0, 2))
@@ -908,6 +1137,10 @@ def display_project_info(
             columns = Table.grid(padding=(0, 4), expand=False)
             columns.add_row(left, right)
 
+            cloud_section = _build_cloud_index_status_section(
+                cloud_index_status, cloud_index_status_error
+            )
+
             # --- Note Types bar chart (top 5 by count) ---
             bars_section = None
             if info.statistics.note_types:
@@ -946,6 +1179,8 @@ def display_project_info(
 
             # --- Assemble dashboard ---
             parts: list = [columns, ""]
+            if cloud_section is not None:
+                parts.extend([cloud_section, ""])
             if bars_section:
                 parts.extend([bars_section, ""])
             parts.append(footer)

src/basic_memory/cli/commands/tool.py

@@ -345,7 +345,7 @@ def recent_activity(
         with force_routing(local=local, cloud=cloud):
             result = run_with_cleanup(
                 mcp_recent_activity(
-                    type=type,  # pyright: ignore[reportArgumentType]
+                    type=type or "",
                     depth=depth if depth is not None else 1,
                     timeframe=timeframe if timeframe is not None else "7d",
                     page=page,

src/basic_memory/config.py

@@ -8,7 +8,7 @@ from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
-from typing import Any, Dict, Literal, Optional, List, Tuple
+from typing import TYPE_CHECKING, Any, Dict, Literal, Optional, List, Tuple
 
 from loguru import logger
 from pydantic import AliasChoices, BaseModel, Field, model_validator
@@ -122,6 +122,11 @@ class ProjectEntry(BaseModel):
 class BasicMemoryConfig(BaseSettings):
     """Pydantic model for Basic Memory global configuration."""
 
+    if TYPE_CHECKING:
+        # Pydantic accepts raw constructor data and validates/coerces it at runtime.
+        # Model attributes remain strongly typed after initialization.
+        def __init__(self, **data: Any) -> None: ...
+
     env: Environment = Field(default="dev", description="Environment name")
 
     projects: Dict[str, ProjectEntry] = Field(
@@ -188,16 +193,33 @@ class BasicMemoryConfig(BaseSettings):
         default=None,
         description="Embedding vector dimensions. Auto-detected from provider if not set (384 for FastEmbed, 1536 for OpenAI).",
     )
+    # Trigger: full local rebuilds spend most of their time waiting behind shared
+    # embed flushes, not constructing vectors themselves.
+    # Why: smaller FastEmbed batches cut queue wait far more than they increase
+    # write overhead on real-world projects, which makes full reindex materially faster.
+    # Outcome: default to the smaller local/cloud-safe batch size we benchmarked as
+    # the current best end-to-end setting in the shared vector sync pipeline.
     semantic_embedding_batch_size: int = Field(
-        default=64,
+        default=2,
         description="Batch size for embedding generation.",
         gt=0,
     )
+    semantic_embedding_request_concurrency: int = Field(
+        default=4,
+        description="Maximum number of concurrent provider requests for batched embedding generation when the active provider supports request-level concurrency.",
+        gt=0,
+    )
     semantic_embedding_sync_batch_size: int = Field(
-        default=64,
+        default=2,
         description="Batch size for vector sync orchestration flushes.",
         gt=0,
     )
+    semantic_postgres_prepare_concurrency: int = Field(
+        default=4,
+        description="Number of Postgres entity prepare tasks to run concurrently during vector sync. Postgres only; keep this low to avoid overdriving the database connection pool.",
+        gt=0,
+        le=16,
+    )
     semantic_embedding_cache_dir: str | None = Field(
         default=None,
         description="Optional cache directory for FastEmbed model artifacts.",
@@ -280,6 +302,31 @@ class BasicMemoryConfig(BaseSettings):
         description="Maximum number of files to process concurrently during sync. Limits memory usage on large projects (2000+ files). Lower values reduce memory consumption.",
         gt=0,
     )
+    index_batch_size: int = Field(
+        default=32,
+        description="Maximum number of changed files to load into one indexing batch.",
+        gt=0,
+    )
+    index_batch_max_bytes: int = Field(
+        default=8 * 1024 * 1024,
+        description="Maximum total bytes to load into one indexing batch. Large files still run as single-file batches.",
+        gt=0,
+    )
+    index_parse_max_concurrent: int = Field(
+        default=8,
+        description="Maximum number of markdown parse tasks to run concurrently inside one indexing batch.",
+        gt=0,
+    )
+    index_entity_max_concurrent: int = Field(
+        default=4,
+        description="Maximum number of entity create/update tasks to run concurrently inside one indexing batch.",
+        gt=0,
+    )
+    index_metadata_update_max_concurrent: int = Field(
+        default=4,
+        description="Maximum number of metadata/search refresh tasks to run concurrently inside one indexing batch.",
+        gt=0,
+    )
 
     kebab_filenames: bool = Field(
         default=False,

src/basic_memory/db.py

@@ -44,101 +44,6 @@ _engine: Optional[AsyncEngine] = None
 _session_maker: Optional[async_sessionmaker[AsyncSession]] = None
 
 
-async def _needs_semantic_embedding_backfill(
-    app_config: BasicMemoryConfig,
-    session_maker: async_sessionmaker[AsyncSession],
-) -> bool:
-    """Check if entities exist but vector embeddings are empty.
-
-    This is the reliable way to detect that embeddings need to be generated,
-    regardless of how migrations were applied (fresh DB, upgrade, reset, etc.).
-    """
-    if not app_config.semantic_search_enabled:
-        return False
-
-    try:
-        async with scoped_session(session_maker) as session:
-            entity_count = (
-                await session.execute(text("SELECT COUNT(*) FROM entity"))
-            ).scalar() or 0
-            if entity_count == 0:
-                return False
-
-            # Check if vector chunks table exists and is empty
-            embedding_count = (
-                await session.execute(text("SELECT COUNT(*) FROM search_vector_chunks"))
-            ).scalar() or 0
-
-            return embedding_count == 0
-    except Exception as exc:
-        # Table might not exist yet (pre-migration)
-        logger.debug(f"Could not check embedding status: {exc}")
-        return False
-
-
-async def _run_semantic_embedding_backfill(
-    app_config: BasicMemoryConfig,
-    session_maker: async_sessionmaker[AsyncSession],
-) -> None:
-    """Backfill semantic embeddings for all active projects/entities."""
-    if not app_config.semantic_search_enabled:
-        logger.info("Skipping automatic semantic embedding backfill: semantic search is disabled.")
-        return
-
-    async with scoped_session(session_maker) as session:
-        project_result = await session.execute(
-            text("SELECT id, name FROM project WHERE is_active = :is_active ORDER BY id"),
-            {"is_active": True},
-        )
-        projects = [(int(row[0]), str(row[1])) for row in project_result.fetchall()]
-
-    if not projects:
-        logger.info("Skipping automatic semantic embedding backfill: no active projects found.")
-        return
-
-    repository_class = (
-        PostgresSearchRepository
-        if app_config.database_backend == DatabaseBackend.POSTGRES
-        else SQLiteSearchRepository
-    )
-
-    total_entities = 0
-    for project_id, project_name in projects:
-        async with scoped_session(session_maker) as session:
-            entity_result = await session.execute(
-                text("SELECT id FROM entity WHERE project_id = :project_id ORDER BY id"),
-                {"project_id": project_id},
-            )
-            entity_ids = [int(row[0]) for row in entity_result.fetchall()]
-
-        if not entity_ids:
-            continue
-
-        total_entities += len(entity_ids)
-        logger.info(
-            "Automatic semantic embedding backfill: "
-            f"project={project_name}, entities={len(entity_ids)}"
-        )
-
-        search_repository = repository_class(
-            session_maker,
-            project_id=project_id,
-            app_config=app_config,
-        )
-        batch_result = await search_repository.sync_entity_vectors_batch(entity_ids)
-        if batch_result.entities_failed > 0:
-            logger.warning(
-                "Automatic semantic embedding backfill encountered entity failures: "
-                f"project={project_name}, failed={batch_result.entities_failed}, "
-                f"failed_entity_ids={batch_result.failed_entity_ids}"
-            )
-
-    logger.info(
-        "Automatic semantic embedding backfill complete: "
-        f"projects={len(projects)}, entities={total_entities}"
-    )
-
-
 class DatabaseType(Enum):
     """Types of supported databases."""
 
@@ -521,14 +426,6 @@ async def run_migrations(
         else:
             await SQLiteSearchRepository(session_maker, 1).init_search_index()
 
-        # Check if backfill is needed — actual backfill runs in background
-        # from the MCP server lifespan to avoid blocking startup.
-        if await _needs_semantic_embedding_backfill(app_config, session_maker):
-            logger.info(
-                "Semantic embeddings missing — backfill will run in background after startup"
-            )
-        else:
-            logger.info("Semantic embeddings: up to date")
     except Exception as e:  # pragma: no cover
         logger.error(f"Error running migrations: {e}")
         raise

src/basic_memory/file_utils.py

@@ -114,7 +114,13 @@ async def write_file_atomic(path: FilePath, content: str) -> None:
     temp_path = path_obj.with_suffix(".tmp")
 
     try:
-        # Use aiofiles for non-blocking write
+        # Trigger: callers hand us normalized Python text, but the final bytes are allowed
+        #          to use the host platform's native newline convention during the write.
+        # Why: preserving CRLF on Windows keeps local files aligned with editors like
+        #      Obsidian, while FileService now hashes the persisted file bytes instead of
+        #      the pre-write string.
+        # Outcome: this async write stays editor-friendly across platforms without
+        #          reintroducing checksum drift in sync or move detection.
         async with aiofiles.open(temp_path, mode="w", encoding="utf-8") as f:
             await f.write(content)
 
@@ -168,6 +174,13 @@ async def format_markdown_builtin(path: Path) -> Optional[str]:
 
         # Only write if content changed
         if formatted_content != content:
+            # Trigger: mdformat may rewrite markdown content, then the host platform
+            #          decides the newline bytes for the follow-up async text write.
+            # Why: we want formatter output to preserve native newlines instead of
+            #      forcing LF, and the authoritative checksum comes from rereading the
+            #      stored file bytes later in FileService.
+            # Outcome: formatting remains compatible with local editors on Windows while
+            #          checksum-based sync logic stays anchored to on-disk bytes.
             async with aiofiles.open(path, mode="w", encoding="utf-8") as f:
                 await f.write(formatted_content)
 

src/basic_memory/importers/utils.py

@@ -39,23 +39,24 @@ def format_timestamp(timestamp: Any) -> str:  # pragma: no cover
     Returns:
         A formatted string representation of the timestamp.
     """
+    parsed_timestamp = timestamp
     if isinstance(timestamp, str):
         try:
             # Try ISO format
-            timestamp = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+            parsed_timestamp = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
         except ValueError:
             try:
                 # Try unix timestamp as string
-                timestamp = datetime.fromtimestamp(float(timestamp)).astimezone()
+                parsed_timestamp = datetime.fromtimestamp(float(timestamp)).astimezone()
             except ValueError:
                 # Return as is if we can't parse it
                 return timestamp
     elif isinstance(timestamp, (int, float)):
         # Unix timestamp
-        timestamp = datetime.fromtimestamp(timestamp).astimezone()
+        parsed_timestamp = datetime.fromtimestamp(timestamp).astimezone()
 
-    if isinstance(timestamp, datetime):
-        return timestamp.strftime("%Y-%m-%d %H:%M:%S")
+    if isinstance(parsed_timestamp, datetime):
+        return parsed_timestamp.strftime("%Y-%m-%d %H:%M:%S")
 
     # Return as is if we can't format it
-    return str(timestamp)  # pragma: no cover
+    return str(parsed_timestamp)  # pragma: no cover

src/basic_memory/indexing/__init__.py

@@ -0,0 +1,29 @@
+"""Reusable indexing primitives shared by local sync and future remote callers."""
+
+from basic_memory.indexing.batch_indexer import BatchIndexer
+from basic_memory.indexing.batching import build_index_batches
+from basic_memory.indexing.models import (
+    IndexedEntity,
+    IndexBatch,
+    IndexFileMetadata,
+    IndexFileWriter,
+    IndexFrontmatterUpdate,
+    IndexFrontmatterWriteResult,
+    IndexingBatchResult,
+    IndexInputFile,
+    IndexProgress,
+)
+
+__all__ = [
+    "BatchIndexer",
+    "IndexedEntity",
+    "IndexBatch",
+    "IndexFileMetadata",
+    "IndexFileWriter",
+    "IndexFrontmatterUpdate",
+    "IndexFrontmatterWriteResult",
+    "IndexingBatchResult",
+    "IndexInputFile",
+    "IndexProgress",
+    "build_index_batches",
+]

src/basic_memory/indexing/batch_indexer.py

@@ -0,0 +1,556 @@
+"""Reusable batch executor for bounded-parallel file indexing."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Awaitable, Callable, Mapping, TypeVar
+
+from loguru import logger
+from sqlalchemy.exc import IntegrityError
+
+from basic_memory.config import BasicMemoryConfig
+from basic_memory.file_utils import compute_checksum, has_frontmatter
+from basic_memory.markdown.schemas import EntityMarkdown
+from basic_memory.indexing.models import (
+    IndexedEntity,
+    IndexFileWriter,
+    IndexFrontmatterUpdate,
+    IndexingBatchResult,
+    IndexInputFile,
+)
+from basic_memory.models import Entity, Relation
+from basic_memory.services import EntityService
+from basic_memory.services.exceptions import SyncFatalError
+from basic_memory.services.search_service import SearchService
+from basic_memory.repository import EntityRepository, RelationRepository
+
+T = TypeVar("T")
+
+
+@dataclass(slots=True)
+class _PreparedMarkdownFile:
+    file: IndexInputFile
+    content: str
+    final_checksum: str
+    markdown: EntityMarkdown
+    file_contains_frontmatter: bool
+
+
+@dataclass(slots=True)
+class _PreparedEntity:
+    path: str
+    entity_id: int
+    checksum: str
+    content_type: str | None
+    search_content: str | None
+    markdown_content: str | None = None
+
+
+class BatchIndexer:
+    """Index already-loaded files without assuming where they came from."""
+
+    def __init__(
+        self,
+        *,
+        app_config: BasicMemoryConfig,
+        entity_service: EntityService,
+        entity_repository: EntityRepository,
+        relation_repository: RelationRepository,
+        search_service: SearchService,
+        file_writer: IndexFileWriter,
+    ) -> None:
+        self.app_config = app_config
+        self.entity_service = entity_service
+        self.entity_repository = entity_repository
+        self.relation_repository = relation_repository
+        self.search_service = search_service
+        self.file_writer = file_writer
+
+    async def index_files(
+        self,
+        files: Mapping[str, IndexInputFile],
+        *,
+        max_concurrent: int,
+        parse_max_concurrent: int | None = None,
+        existing_permalink_by_path: dict[str, str | None] | None = None,
+    ) -> IndexingBatchResult:
+        """Index one batch of loaded files with bounded concurrency."""
+        if max_concurrent <= 0:
+            raise ValueError("max_concurrent must be greater than zero")
+
+        ordered_paths = sorted(files)
+        if not ordered_paths:
+            return IndexingBatchResult()
+
+        parse_limit = parse_max_concurrent or max_concurrent
+        error_by_path: dict[str, str] = {}
+
+        markdown_paths = [path for path in ordered_paths if self._is_markdown(files[path])]
+        regular_paths = [path for path in ordered_paths if path not in markdown_paths]
+
+        prepared_markdown, parse_errors = await self._run_bounded(
+            markdown_paths,
+            limit=parse_limit,
+            worker=lambda path: self._prepare_markdown_file(files[path]),
+        )
+        error_by_path.update(parse_errors)
+
+        prepared_markdown, normalization_errors = await self._normalize_markdown_batch(
+            prepared_markdown,
+            existing_permalink_by_path=existing_permalink_by_path,
+        )
+        error_by_path.update(normalization_errors)
+
+        indexed_entities: list[IndexedEntity] = []
+        resolved_count = 0
+        unresolved_count = 0
+        search_indexed = 0
+
+        prepared_entities: dict[str, _PreparedEntity] = {}
+
+        markdown_upserts, markdown_errors = await self._run_bounded(
+            [path for path in markdown_paths if path not in error_by_path],
+            limit=max_concurrent,
+            worker=lambda path: self._upsert_markdown_file(prepared_markdown[path]),
+        )
+        error_by_path.update(markdown_errors)
+        prepared_entities.update(markdown_upserts)
+
+        regular_upserts, regular_errors = await self._run_bounded(
+            regular_paths,
+            limit=max_concurrent,
+            worker=lambda path: self._upsert_regular_file(files[path]),
+        )
+        error_by_path.update(regular_errors)
+        prepared_entities.update(regular_upserts)
+
+        markdown_entity_ids = [
+            prepared_entities[path].entity_id
+            for path in markdown_paths
+            if path in prepared_entities
+        ]
+        if markdown_entity_ids:
+            resolved_count, unresolved_count = await self._resolve_batch_relations(
+                markdown_entity_ids,
+                max_concurrent=max_concurrent,
+            )
+
+        refreshed_entities = await self.entity_repository.find_by_ids(
+            [prepared.entity_id for prepared in prepared_entities.values()]
+        )
+        entities_by_id = {entity.id: entity for entity in refreshed_entities}
+
+        refreshed, refresh_errors = await self._run_bounded(
+            [path for path in ordered_paths if path in prepared_entities],
+            limit=self.app_config.index_metadata_update_max_concurrent,
+            worker=lambda path: self._refresh_search_index(
+                prepared_entities[path],
+                entities_by_id[prepared_entities[path].entity_id],
+            ),
+        )
+        error_by_path.update(refresh_errors)
+
+        for path in ordered_paths:
+            indexed = refreshed.get(path)
+            if indexed is not None:
+                indexed_entities.append(indexed)
+
+        search_indexed = len(indexed_entities)
+
+        return IndexingBatchResult(
+            indexed=indexed_entities,
+            errors=[(path, error_by_path[path]) for path in ordered_paths if path in error_by_path],
+            relations_resolved=resolved_count,
+            relations_unresolved=unresolved_count,
+            search_indexed=search_indexed,
+        )
+
+    # --- Preparation ---
+
+    async def _prepare_markdown_file(self, file: IndexInputFile) -> _PreparedMarkdownFile:
+        if file.content is None:
+            raise ValueError(f"Missing content for markdown file: {file.path}")
+
+        content = file.content.decode("utf-8")
+        file_contains_frontmatter = has_frontmatter(content)
+        final_checksum = await self._resolve_checksum(file)
+        entity_markdown = await self.entity_service.entity_parser.parse_markdown_content(
+            file_path=Path(file.path),
+            content=content,
+            mtime=file.last_modified.timestamp() if file.last_modified else None,
+            ctime=file.created_at.timestamp() if file.created_at else None,
+        )
+
+        return _PreparedMarkdownFile(
+            file=file,
+            content=content,
+            final_checksum=final_checksum,
+            markdown=entity_markdown,
+            file_contains_frontmatter=file_contains_frontmatter,
+        )
+
+    async def _normalize_markdown_batch(
+        self,
+        prepared_markdown: dict[str, _PreparedMarkdownFile],
+        *,
+        existing_permalink_by_path: dict[str, str | None] | None = None,
+    ) -> tuple[dict[str, _PreparedMarkdownFile], dict[str, str]]:
+        if not prepared_markdown:
+            return {}, {}
+
+        if existing_permalink_by_path is None:
+            existing_permalink_by_path = {
+                path: permalink
+                for path, permalink in (
+                    await self.entity_repository.get_file_path_to_permalink_map()
+                ).items()
+            }
+
+        batch_paths = set(prepared_markdown)
+        reserved_permalinks = {
+            permalink
+            for path, permalink in existing_permalink_by_path.items()
+            if path not in batch_paths and permalink
+        }
+
+        normalized: dict[str, _PreparedMarkdownFile] = {}
+        errors: dict[str, str] = {}
+
+        for path in sorted(prepared_markdown):
+            try:
+                normalized[path] = await self._normalize_markdown_file(
+                    prepared_markdown[path],
+                    reserved_permalinks,
+                )
+                existing_permalink_by_path[path] = normalized[path].markdown.frontmatter.permalink
+            except Exception as exc:
+                errors[path] = str(exc)
+                logger.warning("Batch markdown normalization failed", path=path, error=str(exc))
+
+        return normalized, errors
+
+    async def _normalize_markdown_file(
+        self,
+        prepared: _PreparedMarkdownFile,
+        reserved_permalinks: set[str],
+    ) -> _PreparedMarkdownFile:
+        final_checksum = prepared.final_checksum
+        final_content = prepared.content
+        final_permalink = await self._resolve_batch_permalink(prepared, reserved_permalinks)
+
+        # Trigger: markdown file has no frontmatter and sync enforcement is enabled.
+        # Why: downstream indexing relies on normalized metadata and stable permalinks.
+        # Outcome: write derived metadata back through the storage-agnostic writer.
+        if not prepared.file_contains_frontmatter and self.app_config.ensure_frontmatter_on_sync:
+            frontmatter_updates = {
+                "title": prepared.markdown.frontmatter.title,
+                "type": prepared.markdown.frontmatter.type,
+                "permalink": final_permalink,
+            }
+            write_result = await self.file_writer.write_frontmatter(
+                IndexFrontmatterUpdate(path=prepared.file.path, metadata=frontmatter_updates)
+            )
+            final_checksum = write_result.checksum
+            final_content = write_result.content
+            prepared.markdown.frontmatter.metadata.update(frontmatter_updates)
+
+        # Trigger: existing markdown frontmatter may lack the canonical permalink.
+        # Why: batch sync keeps permalinks stable without forcing a full rewrite when unchanged.
+        # Outcome: only the permalink field is updated when it actually differs.
+        elif (
+            prepared.file_contains_frontmatter
+            and not self.app_config.disable_permalinks
+            and final_permalink != prepared.markdown.frontmatter.permalink
+        ):
+            prepared.markdown.frontmatter.metadata["permalink"] = final_permalink
+            write_result = await self.file_writer.write_frontmatter(
+                IndexFrontmatterUpdate(
+                    path=prepared.file.path,
+                    metadata={"permalink": final_permalink},
+                )
+            )
+            final_checksum = write_result.checksum
+            final_content = write_result.content
+
+        return _PreparedMarkdownFile(
+            file=prepared.file,
+            content=final_content,
+            final_checksum=final_checksum,
+            markdown=prepared.markdown,
+            file_contains_frontmatter=prepared.file_contains_frontmatter,
+        )
+
+    async def _resolve_batch_permalink(
+        self,
+        prepared: _PreparedMarkdownFile,
+        reserved_permalinks: set[str],
+    ) -> str | None:
+        should_resolve_permalink = (
+            not prepared.file_contains_frontmatter and self.app_config.ensure_frontmatter_on_sync
+        ) or (prepared.file_contains_frontmatter and not self.app_config.disable_permalinks)
+        if not should_resolve_permalink:
+            permalink = prepared.markdown.frontmatter.permalink
+            if permalink:
+                reserved_permalinks.add(permalink)
+            return permalink
+
+        desired_permalink = await self.entity_service.resolve_permalink(
+            prepared.file.path,
+            markdown=prepared.markdown,
+            skip_conflict_check=True,
+        )
+        return self._reserve_batch_permalink(desired_permalink, reserved_permalinks)
+
+    def _reserve_batch_permalink(
+        self,
+        desired_permalink: str,
+        reserved_permalinks: set[str],
+    ) -> str:
+        permalink = desired_permalink
+        suffix = 1
+        while permalink in reserved_permalinks:
+            permalink = f"{desired_permalink}-{suffix}"
+            suffix += 1
+        reserved_permalinks.add(permalink)
+        return permalink
+
+    # --- Persistence ---
+
+    async def _upsert_markdown_file(self, prepared: _PreparedMarkdownFile) -> _PreparedEntity:
+        existing = await self.entity_repository.get_by_file_path(
+            prepared.file.path,
+            load_relations=False,
+        )
+        entity = await self.entity_service.upsert_entity_from_markdown(
+            Path(prepared.file.path),
+            prepared.markdown,
+            is_new=existing is None,
+        )
+        updated = await self.entity_repository.update(
+            entity.id,
+            self._entity_metadata_updates(prepared.file, prepared.final_checksum),
+        )
+        if updated is None:
+            raise ValueError(f"Failed to update markdown entity metadata for {prepared.file.path}")
+
+        return _PreparedEntity(
+            path=prepared.file.path,
+            entity_id=updated.id,
+            checksum=prepared.final_checksum,
+            content_type=prepared.file.content_type,
+            search_content=(
+                prepared.markdown.content
+                if prepared.markdown.content is not None
+                else prepared.content
+            ),
+            markdown_content=prepared.content,
+        )
+
+    async def _upsert_regular_file(self, file: IndexInputFile) -> _PreparedEntity:
+        checksum = await self._resolve_checksum(file)
+        existing = await self.entity_repository.get_by_file_path(file.path, load_relations=False)
+        is_new_entity = existing is None
+
+        if existing is None:
+            await self.entity_service.resolve_permalink(file.path, skip_conflict_check=True)
+            entity = Entity(
+                note_type="file",
+                file_path=file.path,
+                checksum=checksum,
+                title=Path(file.path).name,
+                created_at=file.created_at or datetime.now().astimezone(),
+                updated_at=file.last_modified or datetime.now().astimezone(),
+                content_type=file.content_type or "text/plain",
+                mtime=file.last_modified.timestamp() if file.last_modified else None,
+                size=file.size,
+            )
+
+            try:
+                created = await self.entity_repository.add(entity)
+                entity_id = created.id
+            except IntegrityError as exc:
+                message = str(exc)
+                if (
+                    "UNIQUE constraint failed: entity.file_path" in message
+                    or "uix_entity_file_path_project" in message
+                    or (
+                        "duplicate key value violates unique constraint" in message
+                        and "file_path" in message
+                    )
+                ):
+                    existing = await self.entity_repository.get_by_file_path(
+                        file.path,
+                        load_relations=False,
+                    )
+                    if existing is None:
+                        raise ValueError(
+                            f"Entity not found after file_path conflict: {file.path}"
+                        ) from exc
+                    entity_id = existing.id
+                else:
+                    raise
+        else:
+            entity_id = existing.id
+
+        updated = await self.entity_repository.update(
+            entity_id,
+            self._entity_metadata_updates(file, checksum, include_created_at=is_new_entity),
+        )
+        if updated is None:
+            raise ValueError(f"Failed to update file entity metadata for {file.path}")
+
+        return _PreparedEntity(
+            path=file.path,
+            entity_id=updated.id,
+            checksum=checksum,
+            content_type=file.content_type,
+            search_content=None,
+            markdown_content=None,
+        )
+
+    # --- Relations ---
+
+    async def _resolve_batch_relations(
+        self,
+        entity_ids: list[int],
+        *,
+        max_concurrent: int,
+    ) -> tuple[int, int]:
+        unresolved_relation_lists = await asyncio.gather(
+            *(
+                self.relation_repository.find_unresolved_relations_for_entity(entity_id)
+                for entity_id in entity_ids
+            )
+        )
+        unresolved_relations = [
+            relation for relation_list in unresolved_relation_lists for relation in relation_list
+        ]
+
+        if not unresolved_relations:
+            return 0, 0
+
+        semaphore = asyncio.Semaphore(max_concurrent)
+
+        async def resolve_relation(relation: Relation) -> int:
+            async with semaphore:
+                try:
+                    resolved_entity = await self.entity_service.link_resolver.resolve_link(
+                        relation.to_name
+                    )
+                    if resolved_entity is None or resolved_entity.id == relation.from_id:
+                        return 0
+
+                    try:
+                        await self.relation_repository.update(
+                            relation.id,
+                            {
+                                "to_id": resolved_entity.id,
+                                "to_name": resolved_entity.title,
+                            },
+                        )
+                    except IntegrityError:
+                        await self.relation_repository.delete(relation.id)
+                    return 1
+                except Exception as exc:  # pragma: no cover - defensive logging
+                    logger.warning(
+                        "Batch relation resolution failed",
+                        relation_id=relation.id,
+                        from_id=relation.from_id,
+                        to_name=relation.to_name,
+                        error=str(exc),
+                    )
+                    return 0
+
+        resolved_counts = await asyncio.gather(
+            *(resolve_relation(relation) for relation in unresolved_relations)
+        )
+
+        remaining_relation_lists = await asyncio.gather(
+            *(
+                self.relation_repository.find_unresolved_relations_for_entity(entity_id)
+                for entity_id in entity_ids
+            )
+        )
+        remaining_unresolved = sum(len(relations) for relations in remaining_relation_lists)
+
+        return sum(resolved_counts), remaining_unresolved
+
+    # --- Search refresh ---
+
+    async def _refresh_search_index(
+        self, prepared: _PreparedEntity, entity: Entity
+    ) -> IndexedEntity:
+        await self.search_service.index_entity_data(entity, content=prepared.search_content)
+        return IndexedEntity(
+            path=prepared.path,
+            entity_id=entity.id,
+            permalink=entity.permalink,
+            checksum=prepared.checksum,
+            content_type=prepared.content_type,
+            markdown_content=prepared.markdown_content,
+        )
+
+    # --- Helpers ---
+
+    async def _resolve_checksum(self, file: IndexInputFile) -> str:
+        if file.checksum is not None:
+            return file.checksum
+        if file.content is None:
+            raise ValueError(f"Missing checksum and content for file: {file.path}")
+        return await compute_checksum(file.content)
+
+    def _entity_metadata_updates(
+        self,
+        file: IndexInputFile,
+        checksum: str,
+        *,
+        include_created_at: bool = True,
+    ) -> dict[str, object]:
+        updates: dict[str, object] = {
+            "file_path": file.path,
+            "checksum": checksum,
+            "size": file.size,
+        }
+        if include_created_at and file.created_at is not None:
+            updates["created_at"] = file.created_at
+        if file.last_modified is not None:
+            updates["updated_at"] = file.last_modified
+            updates["mtime"] = file.last_modified.timestamp()
+        if file.content_type is not None:
+            updates["content_type"] = file.content_type
+        return updates
+
+    def _is_markdown(self, file: IndexInputFile) -> bool:
+        if file.content_type is not None:
+            return file.content_type == "text/markdown"
+        return Path(file.path).suffix.lower() in {".md", ".markdown"}
+
+    async def _run_bounded(
+        self,
+        paths: list[str],
+        *,
+        limit: int,
+        worker: Callable[[str], Awaitable[T]],
+    ) -> tuple[dict[str, T], dict[str, str]]:
+        if not paths:
+            return {}, {}
+
+        semaphore = asyncio.Semaphore(limit)
+        results: dict[str, T] = {}
+        errors: dict[str, str] = {}
+
+        async def run(path: str) -> None:
+            async with semaphore:
+                try:
+                    results[path] = await worker(path)
+                except Exception as exc:
+                    if isinstance(exc, SyncFatalError) or isinstance(exc.__cause__, SyncFatalError):
+                        raise
+                    errors[path] = str(exc)
+                    logger.warning("Batch indexing failed", path=path, error=str(exc))
+
+        await asyncio.gather(*(run(path) for path in paths))
+        return results, errors

src/basic_memory/indexing/batching.py

@@ -0,0 +1,63 @@
+"""Deterministic helpers for planning bounded indexing batches."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from basic_memory.indexing.models import IndexBatch, IndexFileMetadata
+
+
+def build_index_batches(
+    paths: Sequence[str],
+    metadata_by_path: Mapping[str, IndexFileMetadata],
+    *,
+    max_files: int,
+    max_bytes: int,
+) -> list[IndexBatch]:
+    """Build deterministic batches bounded by file count and total bytes."""
+    if max_files <= 0:
+        raise ValueError("max_files must be greater than zero")
+    if max_bytes <= 0:
+        raise ValueError("max_bytes must be greater than zero")
+
+    ordered_paths = sorted(paths)
+    batches: list[IndexBatch] = []
+    current_paths: list[str] = []
+    current_bytes = 0
+
+    for path in ordered_paths:
+        metadata = metadata_by_path.get(path)
+        if metadata is None:
+            raise KeyError(f"Missing metadata for path: {path}")
+
+        file_bytes = max(metadata.size, 0)
+
+        # Trigger: the next file would overflow the active batch.
+        # Why: keep batches memory-bounded and predictable for both local and remote callers.
+        # Outcome: flush the current batch before placing the next file.
+        if current_paths and (
+            len(current_paths) >= max_files or current_bytes + file_bytes > max_bytes
+        ):
+            batches.append(IndexBatch(paths=current_paths, total_bytes=current_bytes))
+            current_paths = []
+            current_bytes = 0
+
+        # Trigger: one file is larger than the configured byte budget.
+        # Why: we still need to index it, but splitting a single file is out of scope.
+        # Outcome: emit a dedicated single-file batch that may exceed max_bytes.
+        if file_bytes > max_bytes:
+            batches.append(IndexBatch(paths=[path], total_bytes=file_bytes))
+            continue
+
+        current_paths.append(path)
+        current_bytes += file_bytes
+
+        if len(current_paths) >= max_files or current_bytes == max_bytes:
+            batches.append(IndexBatch(paths=current_paths, total_bytes=current_bytes))
+            current_paths = []
+            current_bytes = 0
+
+    if current_paths:
+        batches.append(IndexBatch(paths=current_paths, total_bytes=current_bytes))
+
+    return batches

src/basic_memory/indexing/models.py

@@ -0,0 +1,94 @@
+"""Typed models for the reusable indexing execution path."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Protocol
+
+
+@dataclass(slots=True)
+class IndexFileMetadata:
+    """Storage-agnostic metadata for a file queued for indexing."""
+
+    path: str
+    size: int
+    checksum: str | None = None
+    content_type: str | None = None
+    last_modified: datetime | None = None
+    created_at: datetime | None = None
+
+
+@dataclass(slots=True)
+class IndexInputFile(IndexFileMetadata):
+    """Fully loaded file payload consumed by the batch executor."""
+
+    content: bytes | None = None
+
+
+@dataclass(slots=True)
+class IndexBatch:
+    """A deterministic batch of files bounded by count and total bytes."""
+
+    paths: list[str]
+    total_bytes: int
+
+
+@dataclass(slots=True)
+class IndexProgress:
+    """Batch indexing progress emitted to callers such as the CLI."""
+
+    files_total: int
+    files_processed: int
+    batches_total: int
+    batches_completed: int
+    current_batch_bytes: int = 0
+    files_per_minute: float = 0.0
+    eta_seconds: float | None = None
+
+
+@dataclass(slots=True)
+class IndexFrontmatterUpdate:
+    """A typed frontmatter write request for a single file."""
+
+    path: str
+    metadata: dict[str, Any]
+
+
+@dataclass(slots=True)
+class IndexFrontmatterWriteResult:
+    """Typed result for a frontmatter write performed during indexing."""
+
+    checksum: str
+    content: str
+
+
+@dataclass(slots=True)
+class IndexedEntity:
+    """Stable output describing one file that finished indexing successfully."""
+
+    path: str
+    entity_id: int
+    permalink: str | None
+    checksum: str
+    content_type: str | None = None
+    markdown_content: str | None = None
+
+
+@dataclass(slots=True)
+class IndexingBatchResult:
+    """Outcome for one batch execution."""
+
+    indexed: list[IndexedEntity] = field(default_factory=list)
+    errors: list[tuple[str, str]] = field(default_factory=list)
+    relations_resolved: int = 0
+    relations_unresolved: int = 0
+    search_indexed: int = 0
+
+
+class IndexFileWriter(Protocol):
+    """Narrow protocol for frontmatter writes during indexing."""
+
+    async def write_frontmatter(
+        self, update: IndexFrontmatterUpdate
+    ) -> IndexFrontmatterWriteResult: ...

src/basic_memory/markdown/entity_parser.py

@@ -249,6 +249,10 @@ class EntityParser:
 
         content = strip_bom(content)
 
+        # PostgreSQL rejects null bytes (0x00) in text columns.
+        # Some markdown files (e.g. Claude agent definitions) contain embedded nulls.
+        content = content.replace("\x00", "")
+
         # Parse frontmatter with proper error handling for malformed YAML.
         # We use frontmatter.parse() instead of frontmatter.loads() because
         # loads() does Post(content, handler, **metadata), which crashes when

src/basic_memory/markdown/schemas.py

@@ -1,9 +1,9 @@
 """Schema models for entity markdown files."""
 
 from datetime import datetime
-from typing import List, Optional
+from typing import TYPE_CHECKING, Any, List, Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field, model_validator
 
 
 class Observation(BaseModel):
@@ -38,23 +38,47 @@ class Relation(BaseModel):
 class EntityFrontmatter(BaseModel):
     """Required frontmatter fields for an entity."""
 
-    metadata: dict = {}
+    if TYPE_CHECKING:
+        # Frontmatter may be built from raw YAML keys. The validator below
+        # gathers those keys into the metadata mapping used at runtime.
+        def __init__(self, **data: Any) -> None: ...
+
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def collect_metadata(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+
+        if "metadata" not in data:
+            return {"metadata": data}
+
+        metadata = data.get("metadata") or {}
+        extras = {key: value for key, value in data.items() if key != "metadata"}
+        if extras:
+            return {"metadata": {**extras, **metadata}}
+        return data
 
     @property
     def tags(self) -> List[str]:
-        return self.metadata.get("tags") if self.metadata else None  # pyright: ignore
+        tags = self.metadata.get("tags")
+        return [str(tag) for tag in tags] if isinstance(tags, list) else []
 
     @property
     def title(self) -> str:
-        return self.metadata.get("title") if self.metadata else None  # pyright: ignore
+        title = self.metadata.get("title")
+        return title if isinstance(title, str) else ""
 
     @property
     def type(self) -> str:
-        return self.metadata.get("type", "note") if self.metadata else "note"  # pyright: ignore
+        note_type = self.metadata.get("type", "note")
+        return note_type if isinstance(note_type, str) else "note"
 
     @property
-    def permalink(self) -> str:
-        return self.metadata.get("permalink") if self.metadata else None  # pyright: ignore
+    def permalink(self) -> Optional[str]:
+        permalink = self.metadata.get("permalink")
+        return permalink if isinstance(permalink, str) else None
 
 
 class EntityMarkdown(BaseModel):

src/basic_memory/mcp/async_client.py

@@ -128,11 +128,14 @@ async def get_cloud_control_plane_client(
         yield client
 
 
-# Optional factory override for dependency injection
-_client_factory: Optional[Callable[[], AbstractAsyncContextManager[AsyncClient]]] = None
+# Optional factory override for dependency injection.
+# The factory accepts an optional workspace keyword argument so that MCP tools
+# can route individual requests to a different workspace than the one set at
+# connection time.  See basic-memory-cloud main.py tenant_asgi_client_factory.
+_client_factory: Optional[Callable[..., AbstractAsyncContextManager[AsyncClient]]] = None
 
 
-def set_client_factory(factory: Callable[[], AbstractAsyncContextManager[AsyncClient]]) -> None:
+def set_client_factory(factory: Callable[..., AbstractAsyncContextManager[AsyncClient]]) -> None:
     """Override the default client factory (for cloud app, testing, etc)."""
     global _client_factory
     _client_factory = factory
@@ -173,7 +176,7 @@ async def get_client(
     4. Local ASGI transport by default.
     """
     if _client_factory:
-        async with _client_factory() as client:
+        async with _client_factory(workspace=workspace) as client:
             yield client
         return
 

src/basic_memory/mcp/project_context.py

@@ -622,10 +622,10 @@ async def get_project_client(
 
     # Step 1b: Factory injection (in-process cloud server)
     # Trigger: set_client_factory() was called (e.g., by cloud MCP server)
-    # Why: the transport layer already resolved workspace and tenant context;
-    #   attempting cloud workspace resolution here would call the production
-    #   control-plane API with no valid credentials and fail with 401
-    # Outcome: use the factory client directly, skip workspace resolution
+    # Why: the factory's transport layer handles auth and tenant resolution;
+    #   we pass workspace through so the transport can route to the correct
+    #   workspace when the tool specifies one different from the connection default
+    # Outcome: factory client with optional workspace override via inner request headers
     if is_factory_mode():
         route_mode = "factory"
         with telemetry.scope(
@@ -635,7 +635,7 @@ async def get_project_client(
             workspace_id=workspace,
         ):
             logger.debug("Using injected client factory for project routing")
-            async with get_client() as client:
+            async with get_client(workspace=workspace) as client:
                 active_project = await get_active_project(client, resolved_project, context)
                 yield client, active_project
         return

src/basic_memory/mcp/prompts/utils.py

@@ -95,8 +95,8 @@ def format_prompt_context(context: PromptContext) -> str:
     sections = []
 
     # Process each context
-    for context in context.results:  # pyright: ignore
-        for primary in context.primary_results:  # pyright: ignore
+    for context_item in context.results:
+        for primary in context_item.primary_results:
             if primary.permalink not in added_permalinks:
                 primary_permalink = primary.permalink
 
@@ -121,8 +121,8 @@ def format_prompt_context(context: PromptContext) -> str:
                 section += f"- **Created**: {primary.created_at.strftime('%Y-%m-%d %H:%M')}\n"
 
                 # Add content snippet
-                if hasattr(primary, "content") and primary.content:  # pyright: ignore
-                    content = primary.content or ""  # pyright: ignore  # pragma: no cover
+                if hasattr(primary, "content") and primary.content:
+                    content = primary.content or ""  # pragma: no cover
                     if content:  # pragma: no cover
                         section += f"\n**Excerpt**:\n{content}\n"  # pragma: no cover
 
@@ -132,14 +132,14 @@ def format_prompt_context(context: PromptContext) -> str:
                     """)
                 sections.append(section)
 
-        if context.related_results:  # pyright: ignore
-            section += dedent(  # pyright: ignore
+        if context_item.related_results:
+            section += dedent(
                 """   
                 ## Related Context
                 """
             )
 
-            for related in context.related_results:  # pyright: ignore
+            for related in context_item.related_results:
                 section_content = dedent(f"""
                     - type: **{related.type}**
                     - title: {related.title}

src/basic_memory/mcp/server.py

@@ -2,7 +2,6 @@
 Basic Memory FastMCP server.
 """
 
-import asyncio
 import time
 from contextlib import asynccontextmanager
 
@@ -13,12 +12,7 @@ from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession
 
 from basic_memory import db
 from basic_memory.cli.auth import CLIAuth
-from basic_memory.config import BasicMemoryConfig
-from basic_memory.db import (
-    scoped_session,
-    _needs_semantic_embedding_backfill,
-    _run_semantic_embedding_backfill,
-)
+from basic_memory.db import scoped_session
 from basic_memory.mcp.container import McpContainer, set_container
 from basic_memory.services.initialization import initialize_app
 from basic_memory import telemetry
@@ -43,7 +37,7 @@ async def _log_embedding_status(session_maker: async_sessionmaker[AsyncSession])
         elif embedding_count == 0:
             logger.warning(
                 f"Semantic embeddings: EMPTY — {entity_count} entities have no embeddings. "
-                "Backfill running in background..."
+                "Run 'bm reindex --embeddings' to build them."
             )
         else:
             logger.info(
@@ -54,20 +48,6 @@ async def _log_embedding_status(session_maker: async_sessionmaker[AsyncSession])
         logger.debug(f"Could not check embedding status at startup: {exc}")
 
 
-async def _background_embedding_backfill(
-    config: BasicMemoryConfig,
-    session_maker: async_sessionmaker[AsyncSession],
-) -> None:
-    """Run semantic embedding backfill in the background without blocking startup."""
-    try:
-        if await _needs_semantic_embedding_backfill(config, session_maker):
-            logger.info("Background embedding backfill starting...")
-            await _run_semantic_embedding_backfill(config, session_maker)
-            await _log_embedding_status(session_maker)
-    except Exception as exc:
-        logger.error(f"Background embedding backfill failed: {exc}")
-
-
 @asynccontextmanager
 async def lifespan(app: FastMCP):
     """Lifecycle manager for the MCP server.
@@ -133,14 +113,8 @@ async def lifespan(app: FastMCP):
         await initialize_app(container.config)
 
         # Log embedding status so it's easy to spot in the logs
-        backfill_task: asyncio.Task | None = None  # type: ignore[type-arg]
         if config.semantic_search_enabled and db._session_maker is not None:
             await _log_embedding_status(db._session_maker)
-            # Launch backfill in background so MCP server is ready immediately
-            backfill_task = asyncio.create_task(
-                _background_embedding_backfill(config, db._session_maker),
-                name="embedding-backfill",
-            )
 
         # Create and start sync coordinator (lifecycle centralized in coordinator)
         sync_coordinator = container.create_sync_coordinator()
@@ -157,14 +131,6 @@ async def lifespan(app: FastMCP):
         ):
             logger.debug("Shutting down Basic Memory MCP server")
 
-            # Cancel embedding backfill if still running
-            if backfill_task is not None and not backfill_task.done():
-                backfill_task.cancel()
-                try:
-                    await backfill_task
-                except asyncio.CancelledError:
-                    logger.info("Background embedding backfill cancelled during shutdown")
-
             await sync_coordinator.stop()
 
             # Only shutdown DB if we created it (not if test fixture provided it)

src/basic_memory/mcp/tools/read_note.py

@@ -1,7 +1,7 @@
 """Read note tool for Basic Memory MCP server."""
 
 from textwrap import dedent
-from typing import Optional, Literal
+from typing import Optional, Literal, cast
 
 import yaml
 
@@ -235,13 +235,22 @@ async def read_note(
                         "frontmatter": None,
                     }
 
-                def _search_results(payload: object) -> list[dict]:
+                def _search_results(payload: object) -> list[dict[str, object]]:
                     if not isinstance(payload, dict):
                         return []
-                    results = payload.get("results")
-                    return results if isinstance(results, list) else []
+                    payload_dict = cast(dict[str, object], payload)
+                    results = payload_dict.get("results")
+                    if not isinstance(results, list):
+                        return []
+                    return [
+                        cast(dict[str, object], result)
+                        for result in results
+                        if isinstance(result, dict)
+                    ]
 
-                async def _search_candidates(identifier_text: str, *, title_only: bool) -> dict:
+                async def _search_candidates(
+                    identifier_text: str, *, title_only: bool
+                ) -> dict[str, object]:
                     # Trigger: direct entity resolution failed for the caller's identifier.
                     # Why: search_notes applies the same memory:// normalization and tool-level
                     #      query handling as the rest of MCP routing, which raw client calls skip.
@@ -257,16 +266,16 @@ async def read_note(
                         output_format="json",
                         context=context,
                     )
-                    return response if isinstance(response, dict) else {}
+                    return cast(dict[str, object], response) if isinstance(response, dict) else {}
 
-                def _result_title(item: dict) -> str:
+                def _result_title(item: dict[str, object]) -> str:
                     return str(item.get("title") or "")
 
-                def _result_permalink(item: dict) -> Optional[str]:
+                def _result_permalink(item: dict[str, object]) -> Optional[str]:
                     value = item.get("permalink")
                     return str(value) if value else None
 
-                def _result_file_path(item: dict) -> Optional[str]:
+                def _result_file_path(item: dict[str, object]) -> Optional[str]:
                     value = item.get("file_path")
                     return str(value) if value else None
 

src/basic_memory/models/__init__.py

@@ -2,12 +2,13 @@
 
 import basic_memory
 from basic_memory.models.base import Base
-from basic_memory.models.knowledge import Entity, Observation, Relation
+from basic_memory.models.knowledge import Entity, NoteContent, Observation, Relation
 from basic_memory.models.project import Project
 
 __all__ = [
     "Base",
     "Entity",
+    "NoteContent",
     "Observation",
     "Relation",
     "Project",

src/basic_memory/models/base.py

@@ -1,5 +1,7 @@
 """Base model class for SQLAlchemy models."""
 
+from typing import TYPE_CHECKING
+
 from sqlalchemy.ext.asyncio import AsyncAttrs
 from sqlalchemy.orm import DeclarativeBase
 
@@ -7,4 +9,5 @@ from sqlalchemy.orm import DeclarativeBase
 class Base(AsyncAttrs, DeclarativeBase):
     """Base class for all models"""
 
-    pass
+    if TYPE_CHECKING:
+        id: int

src/basic_memory/models/knowledge.py

@@ -6,6 +6,8 @@ from basic_memory.utils import ensure_timezone_aware
 from typing import Optional
 
 from sqlalchemy import (
+    BigInteger,
+    CheckConstraint,
     Integer,
     String,
     Text,
@@ -116,6 +118,12 @@ class Entity(Base):
         foreign_keys="[Relation.to_id]",
         cascade="all, delete-orphan",
     )
+    note_content = relationship(
+        "NoteContent",
+        back_populates="entity",
+        cascade="all, delete-orphan",
+        uselist=False,
+    )
 
     @property
     def relations(self):
@@ -141,6 +149,74 @@ class Entity(Base):
         return f"Entity(id={self.id}, external_id='{self.external_id}', name='{self.title}', type='{self.note_type}', checksum='{self.checksum}')"
 
 
+class NoteContent(Base):
+    """Materialized markdown content and sync state for a note entity."""
+
+    __tablename__ = "note_content"
+    __table_args__ = (
+        CheckConstraint(
+            "file_write_status IN ("
+            "'pending', "
+            "'writing', "
+            "'synced', "
+            "'failed', "
+            "'external_change_detected'"
+            ")",
+            name="ck_note_content_file_write_status",
+        ),
+        Index("ix_note_content_project_id", "project_id"),
+        Index("ix_note_content_file_path", "file_path"),
+        Index("ix_note_content_external_id", "external_id", unique=True),
+    )
+
+    # Core identity mirrored from entity for hot note reads
+    entity_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("entity.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    project_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("project.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    external_id: Mapped[str] = mapped_column(String, nullable=False)
+    file_path: Mapped[str] = mapped_column(String, nullable=False)
+
+    # Materialized content version tracked in the tenant database
+    markdown_content: Mapped[str] = mapped_column(Text, nullable=False)
+    db_version: Mapped[int] = mapped_column(BigInteger, nullable=False)
+    db_checksum: Mapped[str] = mapped_column(String, nullable=False)
+
+    # File materialization state tracked against the latest write attempts
+    file_version: Mapped[Optional[int]] = mapped_column(BigInteger, nullable=True)
+    file_checksum: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    file_write_status: Mapped[str] = mapped_column(String, nullable=False, default="pending")
+    last_source: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now().astimezone(),
+        onupdate=lambda: datetime.now().astimezone(),
+    )
+    file_updated_at: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+    )
+    last_materialization_error: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+    last_materialization_attempt_at: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+    )
+
+    entity = relationship("Entity", back_populates="note_content")
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"NoteContent(entity_id={self.entity_id}, external_id='{self.external_id}', "
+            f"file_path='{self.file_path}', file_write_status='{self.file_write_status}')"
+        )
+
+
 class Observation(Base):
     """An observation about an entity.
 

src/basic_memory/models/search.py

@@ -104,6 +104,8 @@ CREATE TABLE IF NOT EXISTS search_vector_chunks (
     chunk_key TEXT NOT NULL,
     chunk_text TEXT NOT NULL,
     source_hash TEXT NOT NULL,
+    entity_fingerprint TEXT NOT NULL,
+    embedding_model TEXT NOT NULL,
     updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
     UNIQUE (project_id, entity_id, chunk_key)
 )
@@ -124,6 +126,8 @@ CREATE TABLE IF NOT EXISTS search_vector_chunks (
     chunk_key TEXT NOT NULL,
     chunk_text TEXT NOT NULL,
     source_hash TEXT NOT NULL,
+    entity_fingerprint TEXT NOT NULL,
+    embedding_model TEXT NOT NULL,
     updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
 )
 """)

src/basic_memory/repository/__init__.py

@@ -1,10 +1,12 @@
 from .entity_repository import EntityRepository
+from .note_content_repository import NoteContentRepository
 from .observation_repository import ObservationRepository
 from .project_repository import ProjectRepository
 from .relation_repository import RelationRepository
 
 __all__ = [
     "EntityRepository",
+    "NoteContentRepository",
     "ObservationRepository",
     "ProjectRepository",
     "RelationRepository",

src/basic_memory/repository/embedding_provider.py

@@ -1,6 +1,6 @@
 """Embedding provider protocol for pluggable semantic backends."""
 
-from typing import Protocol
+from typing import Any, Protocol
 
 
 class EmbeddingProvider(Protocol):
@@ -16,3 +16,7 @@ class EmbeddingProvider(Protocol):
     async def embed_documents(self, texts: list[str]) -> list[list[float]]:
         """Embed a list of document chunks."""
         ...
+
+    def runtime_log_attrs(self) -> dict[str, Any]:
+        """Return provider-specific runtime settings suitable for startup logs."""
+        ...

src/basic_memory/repository/embedding_provider_factory.py

@@ -1,26 +1,77 @@
 """Factory for creating configured semantic embedding providers."""
 
+import os
 from threading import Lock
 
 from basic_memory.config import BasicMemoryConfig
 from basic_memory.repository.embedding_provider import EmbeddingProvider
 
-type ProviderCacheKey = tuple[str, str, int | None, int, str | None, int | None, int | None]
+type ProviderCacheKey = tuple[
+    str,
+    str,
+    int | None,
+    int,
+    int,
+    str | None,
+    int | None,
+    int | None,
+]
 
 _EMBEDDING_PROVIDER_CACHE: dict[ProviderCacheKey, EmbeddingProvider] = {}
 _EMBEDDING_PROVIDER_CACHE_LOCK = Lock()
+_FASTEMBED_MAX_THREADS = 8
+
+
+def _available_cpu_count() -> int | None:
+    """Return the CPU budget available to this process when the runtime exposes it."""
+    process_cpu_count = getattr(os, "process_cpu_count", None)
+    if callable(process_cpu_count):
+        cpu_count = process_cpu_count()
+        if isinstance(cpu_count, int) and cpu_count > 0:
+            return cpu_count
+
+    cpu_count = os.cpu_count()
+    return cpu_count if cpu_count is not None and cpu_count > 0 else None
+
+
+def _resolve_fastembed_runtime_knobs(
+    app_config: BasicMemoryConfig,
+) -> tuple[int | None, int | None]:
+    """Resolve FastEmbed threads/parallel from explicit config or CPU-aware defaults."""
+    configured_threads = app_config.semantic_embedding_threads
+    configured_parallel = app_config.semantic_embedding_parallel
+    if configured_threads is not None or configured_parallel is not None:
+        return configured_threads, configured_parallel
+
+    available_cpus = _available_cpu_count()
+    if available_cpus is None:
+        return None, None
+
+    # Trigger: local laptops and cloud workers expose different CPU budgets.
+    # Why: full rebuilds got faster when FastEmbed used most, but not all, of
+    # the available CPUs. Leaving a little headroom avoids starving the rest of
+    # the pipeline while still giving ONNX enough threads to stay busy.
+    # Outcome: when config leaves the knobs unset, each process reserves a small
+    # CPU cushion and keeps FastEmbed on the simpler single-process path.
+    if available_cpus <= 2:
+        return available_cpus, 1
+
+    threads = min(_FASTEMBED_MAX_THREADS, max(2, available_cpus - 2))
+    return threads, 1
 
 
 def _provider_cache_key(app_config: BasicMemoryConfig) -> ProviderCacheKey:
     """Build a stable cache key from provider-relevant semantic embedding config."""
+    resolved_threads, resolved_parallel = _resolve_fastembed_runtime_knobs(app_config)
     return (
         app_config.semantic_embedding_provider.strip().lower(),
         app_config.semantic_embedding_model,
         app_config.semantic_embedding_dimensions,
         app_config.semantic_embedding_batch_size,
+        app_config.semantic_embedding_request_concurrency,
         app_config.semantic_embedding_cache_dir,
-        app_config.semantic_embedding_threads,
-        app_config.semantic_embedding_parallel,
+        resolved_threads,
+        resolved_parallel,
     )
 
 
@@ -51,12 +102,13 @@ def create_embedding_provider(app_config: BasicMemoryConfig) -> EmbeddingProvide
         # Deferred import: fastembed (and its onnxruntime dep) may not be installed
         from basic_memory.repository.fastembed_provider import FastEmbedEmbeddingProvider
 
+        resolved_threads, resolved_parallel = _resolve_fastembed_runtime_knobs(app_config)
         if app_config.semantic_embedding_cache_dir is not None:
             extra_kwargs["cache_dir"] = app_config.semantic_embedding_cache_dir
-        if app_config.semantic_embedding_threads is not None:
-            extra_kwargs["threads"] = app_config.semantic_embedding_threads
-        if app_config.semantic_embedding_parallel is not None:
-            extra_kwargs["parallel"] = app_config.semantic_embedding_parallel
+        if resolved_threads is not None:
+            extra_kwargs["threads"] = resolved_threads
+        if resolved_parallel is not None:
+            extra_kwargs["parallel"] = resolved_parallel
 
         provider = FastEmbedEmbeddingProvider(
             model_name=app_config.semantic_embedding_model,
@@ -73,6 +125,7 @@ def create_embedding_provider(app_config: BasicMemoryConfig) -> EmbeddingProvide
         provider = OpenAIEmbeddingProvider(
             model_name=model_name,
             batch_size=app_config.semantic_embedding_batch_size,
+            request_concurrency=app_config.semantic_embedding_request_concurrency,
             **extra_kwargs,
         )
     else:

src/basic_memory/repository/entity_repository.py

@@ -45,7 +45,17 @@ class EntityRepository(Repository[Entity]):
         async with db.scoped_session(self.session_maker) as session:
             return await self.select_by_id(session, entity_id)
 
-    async def get_by_external_id(self, external_id: str) -> Optional[Entity]:
+    async def _find_one_by_query(self, query, *, load_relations: bool) -> Optional[Entity]:
+        """Return one entity row with optional eager loading."""
+        if load_relations:
+            return await self.find_one(query)
+
+        result = await self.execute_query(query, use_query_options=False)
+        return result.scalars().one_or_none()
+
+    async def get_by_external_id(
+        self, external_id: str, *, load_relations: bool = True
+    ) -> Optional[Entity]:
         """Get entity by external UUID.
 
         Args:
@@ -54,19 +64,8 @@ class EntityRepository(Repository[Entity]):
         Returns:
             Entity if found, None otherwise
         """
-        query = (
-            self.select().where(Entity.external_id == external_id).options(*self.get_load_options())
-        )
-        return await self.find_one(query)
-
-    async def _find_one_by_query(self, query, *, load_relations: bool) -> Optional[Entity]:
-        """Return one entity row with optional eager loading."""
-        if load_relations:
-            query = query.options(*self.get_load_options())
-            return await self.find_one(query)
-
-        result = await self.execute_query(query, use_query_options=False)
-        return result.scalars().one_or_none()
+        query = self.select().where(Entity.external_id == external_id)
+        return await self._find_one_by_query(query, load_relations=load_relations)
 
     async def get_by_permalink(
         self, permalink: str, *, load_relations: bool = True
@@ -314,7 +313,7 @@ class EntityRepository(Repository[Entity]):
         result = await self.execute_query(query)
         return list(result.scalars().all())
 
-    async def upsert_entity(self, entity: Entity, *, reload: bool = True) -> Entity:
+    async def upsert_entity(self, entity: Entity) -> Entity:
         """Insert or update entity using simple try/catch with database-level conflict resolution.
 
         Handles file_path race conditions by checking for existing entity on IntegrityError.
@@ -335,9 +334,6 @@ class EntityRepository(Repository[Entity]):
                 session.add(entity)
                 await session.flush()
 
-                if not reload:
-                    return entity
-
                 # Return with relationships loaded
                 query = (
                     self.select()
@@ -374,12 +370,13 @@ class EntityRepository(Repository[Entity]):
                 await session.rollback()
 
                 # Re-query after rollback to get a fresh, attached entity
-                existing_query = select(Entity).where(
-                    Entity.file_path == entity.file_path, Entity.project_id == entity.project_id
+                existing_result = await session.execute(
+                    select(Entity)
+                    .where(
+                        Entity.file_path == entity.file_path, Entity.project_id == entity.project_id
+                    )
+                    .options(*self.get_load_options())
                 )
-                if reload:
-                    existing_query = existing_query.options(*self.get_load_options())
-                existing_result = await session.execute(existing_query)
                 existing_entity = existing_result.scalar_one_or_none()
 
                 if existing_entity:
@@ -391,6 +388,9 @@ class EntityRepository(Repository[Entity]):
                     # Use merge to avoid session state conflicts
                     # Set the ID to update existing entity
                     entity.id = existing_entity.id
+                    # Preserve the stable external_id so that external references
+                    # (e.g. public share links) survive re-indexing
+                    entity.external_id = existing_entity.external_id
 
                     # Ensure observations reference the correct entity_id
                     for obs in entity.observations:
@@ -403,9 +403,6 @@ class EntityRepository(Repository[Entity]):
 
                     await session.commit()
 
-                    if not reload:
-                        return merged_entity
-
                     # Re-query to get proper relationships loaded
                     final_result = await session.execute(
                         select(Entity)

src/basic_memory/repository/fastembed_provider.py

@@ -11,7 +11,7 @@ from basic_memory.repository.embedding_provider import EmbeddingProvider
 from basic_memory.repository.semantic_errors import SemanticDependenciesMissingError
 
 if TYPE_CHECKING:
-    from fastembed import TextEmbedding  # type: ignore[import-not-found]  # pragma: no cover
+    from fastembed import TextEmbedding  # pragma: no cover
 
 
 class FastEmbedEmbeddingProvider(EmbeddingProvider):
@@ -24,6 +24,15 @@ class FastEmbedEmbeddingProvider(EmbeddingProvider):
     def _effective_parallel(self) -> int | None:
         return self.parallel if self.parallel is not None and self.parallel > 1 else None
 
+    def runtime_log_attrs(self) -> dict[str, int | str | None]:
+        """Return the resolved runtime knobs that shape FastEmbed throughput."""
+        return {
+            "provider_batch_size": self.batch_size,
+            "threads": self.threads,
+            "configured_parallel": self.parallel,
+            "effective_parallel": self._effective_parallel(),
+        }
+
     def __init__(
         self,
         model_name: str = "bge-small-en-v1.5",
@@ -53,7 +62,7 @@ class FastEmbedEmbeddingProvider(EmbeddingProvider):
 
             def _create_model() -> "TextEmbedding":
                 try:
-                    from fastembed import TextEmbedding  # type: ignore[import-not-found]
+                    from fastembed import TextEmbedding
                 except (
                     ImportError
                 ) as exc:  # pragma: no cover - exercised via tests with monkeypatch

src/basic_memory/repository/note_content_repository.py

@@ -0,0 +1,191 @@
+"""Repository for managing note materialization state."""
+
+from pathlib import Path
+from typing import Any, Mapping, Optional
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from basic_memory import db
+from basic_memory.models import Entity, NoteContent
+from basic_memory.repository.repository import Repository
+
+NOTE_CONTENT_MUTABLE_FIELDS = frozenset(
+    {
+        "markdown_content",
+        "db_version",
+        "db_checksum",
+        "file_version",
+        "file_checksum",
+        "file_write_status",
+        "last_source",
+        "updated_at",
+        "file_updated_at",
+        "last_materialization_error",
+        "last_materialization_attempt_at",
+    }
+)
+
+
+class NoteContentRepository(Repository[NoteContent]):
+    """Repository for project-scoped note materialization state."""
+
+    def __init__(self, session_maker: async_sessionmaker[AsyncSession], project_id: int):
+        """Initialize with session maker and project-scoped filtering."""
+        super().__init__(session_maker, NoteContent, project_id=project_id)
+
+    def _coerce_note_content(
+        self, data: Mapping[str, Any] | NoteContent
+    ) -> tuple[NoteContent, set[str]]:
+        """Convert input data to a NoteContent model and track explicit fields."""
+        if isinstance(data, NoteContent):
+            model_data = {
+                key: value for key, value in data.__dict__.items() if key in self.valid_columns
+            }
+        else:
+            model_data = {key: value for key, value in data.items() if key in self.valid_columns}
+
+        entity_id = model_data.get("entity_id")
+        if entity_id is None:
+            raise ValueError("entity_id is required for note_content writes")
+
+        return NoteContent(**model_data), set(model_data)
+
+    async def _load_entity_identity(self, session: AsyncSession, entity_id: int) -> Entity:
+        """Load the owning entity so duplicated identity fields stay aligned."""
+        result = await session.execute(select(Entity).where(Entity.id == entity_id))
+        entity = result.scalar_one_or_none()
+        if entity is None:
+            raise ValueError(f"Entity {entity_id} does not exist")
+
+        if self.project_id is not None and entity.project_id != self.project_id:
+            raise ValueError(
+                f"Entity {entity_id} belongs to project {entity.project_id}, "
+                f"not repository project {self.project_id}"
+            )
+
+        return entity
+
+    async def _align_identity_fields(
+        self, session: AsyncSession, note_content: NoteContent
+    ) -> None:
+        """Mirror project identity from entity before persisting note content."""
+        entity = await self._load_entity_identity(session, note_content.entity_id)
+        note_content.project_id = entity.project_id
+        note_content.external_id = entity.external_id
+        note_content.file_path = Path(entity.file_path).as_posix()
+
+    async def get_by_entity_id(self, entity_id: int) -> Optional[NoteContent]:
+        """Get note content by the owning entity identifier."""
+        return await self.find_by_id(entity_id)
+
+    async def get_by_external_id(self, external_id: str) -> Optional[NoteContent]:
+        """Get note content by the mirrored entity external identifier."""
+        query = self.select().where(NoteContent.external_id == external_id)
+        return await self.find_one(query)
+
+    async def get_by_file_path(self, file_path: Path | str) -> Optional[NoteContent]:
+        """Get note content by file path, preferring rows whose entity still owns that path."""
+        normalized_path = Path(file_path).as_posix()
+
+        # Trigger: note_content mirrors entity.file_path but does not enforce project-level uniqueness.
+        # Why: entity renames can leave stale mirrored paths behind until note_content realigns.
+        # Outcome: prefer the row whose current entity path still matches, then the newest mirror.
+        query = (
+            self.select()
+            .join(Entity, Entity.id == NoteContent.entity_id)
+            .where(NoteContent.file_path == normalized_path)
+            .order_by(
+                (Entity.file_path == normalized_path).desc(),
+                NoteContent.updated_at.desc(),
+                NoteContent.entity_id.desc(),
+            )
+            .limit(1)
+            .options(*self.get_load_options())
+        )
+
+        async with db.scoped_session(self.session_maker) as session:
+            result = await session.execute(query)
+            return result.scalars().first()
+
+    async def create(self, data: Mapping[str, Any] | NoteContent) -> NoteContent:
+        """Create a note_content row aligned to its owning entity."""
+        note_content, _ = self._coerce_note_content(data)
+
+        async with db.scoped_session(self.session_maker) as session:
+            await self._align_identity_fields(session, note_content)
+            session.add(note_content)
+            await session.flush()
+
+            created = await self.select_by_id(session, note_content.entity_id)
+            if created is None:  # pragma: no cover
+                raise ValueError(
+                    f"Can't find NoteContent for entity {note_content.entity_id} after add"
+                )
+            return created
+
+    async def upsert(self, data: Mapping[str, Any] | NoteContent) -> NoteContent:
+        """Insert or update note_content while keeping mirrored identity fields in sync."""
+        note_content, provided_fields = self._coerce_note_content(data)
+
+        async with db.scoped_session(self.session_maker) as session:
+            await self._align_identity_fields(session, note_content)
+            existing = await self.select_by_id(session, note_content.entity_id)
+
+            if existing is None:
+                session.add(note_content)
+                await session.flush()
+                created = await self.select_by_id(session, note_content.entity_id)
+                if created is None:  # pragma: no cover
+                    raise ValueError(
+                        f"Can't find NoteContent for entity {note_content.entity_id} after upsert"
+                    )
+                return created
+
+            fields_to_update = (provided_fields - {"entity_id"}) | {
+                "project_id",
+                "external_id",
+                "file_path",
+            }
+            for column_name in fields_to_update:
+                setattr(existing, column_name, getattr(note_content, column_name))
+
+            await session.flush()
+            updated = await self.select_by_id(session, existing.entity_id)
+            if updated is None:  # pragma: no cover
+                raise ValueError(
+                    f"Can't find NoteContent for entity {existing.entity_id} after upsert"
+                )
+            return updated
+
+    async def update_state_fields(self, entity_id: int, **updates: Any) -> Optional[NoteContent]:
+        """Update sync fields and re-align project_id, external_id, and file_path from entity."""
+        invalid_fields = set(updates) - NOTE_CONTENT_MUTABLE_FIELDS
+        if invalid_fields:
+            invalid_list = ", ".join(sorted(invalid_fields))
+            raise ValueError(f"Unsupported note_content update fields: {invalid_list}")
+
+        async with db.scoped_session(self.session_maker) as session:
+            note_content = await self.select_by_id(session, entity_id)
+            if note_content is None:
+                return None
+
+            await self._align_identity_fields(session, note_content)
+            for field_name, value in updates.items():
+                setattr(note_content, field_name, value)
+
+            await session.flush()
+            updated = await self.select_by_id(session, entity_id)
+            if updated is None:  # pragma: no cover
+                raise ValueError(f"Can't find NoteContent for entity {entity_id} after update")
+            return updated
+
+    async def delete_by_entity_id(self, entity_id: int) -> bool:
+        """Delete note_content by entity identifier."""
+        async with db.scoped_session(self.session_maker) as session:
+            note_content = await self.select_by_id(session, entity_id)
+            if note_content is None:
+                return False
+
+            await session.delete(note_content)
+            return True

src/basic_memory/repository/openai_provider.py

@@ -18,6 +18,7 @@ class OpenAIEmbeddingProvider(EmbeddingProvider):
         model_name: str = "text-embedding-3-small",
         *,
         batch_size: int = 64,
+        request_concurrency: int = 4,
         dimensions: int = 1536,
         api_key: str | None = None,
         base_url: str | None = None,
@@ -26,12 +27,20 @@ class OpenAIEmbeddingProvider(EmbeddingProvider):
         self.model_name = model_name
         self.dimensions = dimensions
         self.batch_size = batch_size
+        self.request_concurrency = request_concurrency
         self._api_key = api_key
         self._base_url = base_url
         self._timeout = timeout
         self._client: Any | None = None
         self._client_lock = asyncio.Lock()
 
+    def runtime_log_attrs(self) -> dict[str, int]:
+        """Return the request fan-out knobs that shape API embedding batches."""
+        return {
+            "provider_batch_size": self.batch_size,
+            "request_concurrency": self.request_concurrency,
+        }
+
     async def _get_client(self) -> Any:
         if self._client is not None:
             return self._client
@@ -41,7 +50,7 @@ class OpenAIEmbeddingProvider(EmbeddingProvider):
                 return self._client
 
             try:
-                from openai import AsyncOpenAI  # type: ignore[import-not-found]
+                from openai import AsyncOpenAI
             except ImportError as exc:  # pragma: no cover - covered via monkeypatch tests
                 raise SemanticDependenciesMissingError(
                     "OpenAI dependency is missing. "
@@ -67,25 +76,49 @@ class OpenAIEmbeddingProvider(EmbeddingProvider):
             return []
 
         client = await self._get_client()
-        all_vectors: list[list[float]] = []
+        batches = [
+            texts[start : start + self.batch_size]
+            for start in range(0, len(texts), self.batch_size)
+        ]
+        batch_vectors: list[list[list[float]] | None] = [None] * len(batches)
+        semaphore = asyncio.Semaphore(self.request_concurrency)
 
-        for start in range(0, len(texts), self.batch_size):
-            batch = texts[start : start + self.batch_size]
-            response = await client.embeddings.create(
-                model=self.model_name,
-                input=batch,
-            )
-            vectors_by_index: dict[int, list[float]] = {
-                int(item.index): [float(value) for value in item.embedding]
-                for item in response.data
-            }
+        async def embed_batch(batch_index: int, batch: list[str]) -> None:
+            async with semaphore:
+                response = await client.embeddings.create(
+                    model=self.model_name,
+                    input=batch,
+                )
+
+            vectors_by_index: dict[int, list[float]] = {}
+            for item in response.data:
+                response_index = int(item.index)
+                if response_index in vectors_by_index:
+                    raise RuntimeError(
+                        "OpenAI embedding response returned duplicate vector indexes."
+                    )
+                vectors_by_index[response_index] = [float(value) for value in item.embedding]
+
+            ordered_vectors: list[list[float]] = []
             for index in range(len(batch)):
                 vector = vectors_by_index.get(index)
                 if vector is None:
                     raise RuntimeError(
                         "OpenAI embedding response is missing expected vector index."
                     )
-                all_vectors.append(vector)
+                ordered_vectors.append(vector)
+
+            batch_vectors[batch_index] = ordered_vectors
+
+        await asyncio.gather(
+            *(embed_batch(batch_index, batch) for batch_index, batch in enumerate(batches))
+        )
+
+        all_vectors: list[list[float]] = []
+        for vectors in batch_vectors:
+            if vectors is None:
+                raise RuntimeError("OpenAI embedding batch did not produce vectors.")
+            all_vectors.extend(vectors)
 
         if all_vectors and len(all_vectors[0]) != self.dimensions:
             raise RuntimeError(

src/basic_memory/repository/postgres_search_repository.py

@@ -15,7 +15,10 @@ from basic_memory.config import BasicMemoryConfig, ConfigManager
 from basic_memory.repository.embedding_provider import EmbeddingProvider
 from basic_memory.repository.embedding_provider_factory import create_embedding_provider
 from basic_memory.repository.search_index_row import SearchIndexRow
-from basic_memory.repository.search_repository_base import SearchRepositoryBase
+from basic_memory.repository.search_repository_base import (
+    SearchRepositoryBase,
+    VectorChunkState,
+)
 from basic_memory.repository.metadata_filters import parse_metadata_filters
 from basic_memory.repository.semantic_errors import SemanticDependenciesMissingError
 from basic_memory.schemas.search import SearchItemType, SearchRetrievalMode
@@ -61,6 +64,9 @@ class PostgresSearchRepository(SearchRepositoryBase):
         self._semantic_embedding_sync_batch_size = (
             self._app_config.semantic_embedding_sync_batch_size
         )
+        self._semantic_postgres_prepare_concurrency = (
+            self._app_config.semantic_postgres_prepare_concurrency
+        )
         self._embedding_provider = embedding_provider
         self._vector_dimensions = 384
         self._vector_tables_initialized = False
@@ -285,6 +291,10 @@ class PostgresSearchRepository(SearchRepositoryBase):
                     ) from exc
 
                 # --- Chunks table (dimension-independent, may already exist via migration) ---
+                # Trigger: fresh Postgres projects may not have vector chunk tables yet.
+                # Why: runtime can bootstrap missing tables, but schema evolution must stay
+                # in Alembic to avoid concurrent ALTER TABLE deadlocks during indexing.
+                # Outcome: new installs create the current schema; upgrades rely on migration.
                 await session.execute(
                     text(
                         """
@@ -295,6 +305,8 @@ class PostgresSearchRepository(SearchRepositoryBase):
                             chunk_key TEXT NOT NULL,
                             chunk_text TEXT NOT NULL,
                             source_hash TEXT NOT NULL,
+                            entity_fingerprint TEXT NOT NULL,
+                            embedding_model TEXT NOT NULL,
                             updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
                             UNIQUE (project_id, entity_id, chunk_key)
                         )
@@ -441,35 +453,115 @@ class PostgresSearchRepository(SearchRepositoryBase):
         )
         return [dict(row) for row in vector_result.mappings().all()]
 
+    def _vector_prepare_window_size(self) -> int:
+        """Use a bounded config-driven prepare window for Postgres vector sync."""
+        return self._semantic_postgres_prepare_concurrency
+
+    async def _upsert_scheduled_chunk_records(
+        self,
+        session: AsyncSession,
+        *,
+        entity_id: int,
+        scheduled_records: list[dict[str, str]],
+        existing_by_key: dict[str, VectorChunkState],
+        entity_fingerprint: str,
+        embedding_model: str,
+    ) -> list[tuple[int, str]]:
+        """Use Postgres UPSERT to rewrite only the scheduled chunk rows."""
+        if not scheduled_records:
+            return []
+
+        upsert_params: dict[str, object] = {
+            "project_id": self.project_id,
+            "entity_id": entity_id,
+        }
+        upsert_values: list[str] = []
+        # The SQL template is built from integer enumerate() indices only.
+        # No user-controlled text is interpolated into the statement.
+        for index, record in enumerate(scheduled_records):
+            upsert_params[f"chunk_key_{index}"] = record["chunk_key"]
+            upsert_params[f"chunk_text_{index}"] = record["chunk_text"]
+            upsert_params[f"source_hash_{index}"] = record["source_hash"]
+            upsert_params[f"entity_fingerprint_{index}"] = entity_fingerprint
+            upsert_params[f"embedding_model_{index}"] = embedding_model
+            upsert_values.append(
+                "("
+                ":entity_id, :project_id, "
+                f":chunk_key_{index}, :chunk_text_{index}, :source_hash_{index}, "
+                f":entity_fingerprint_{index}, :embedding_model_{index}, NOW()"
+                ")"
+            )
+
+        upsert_result = await session.execute(
+            text(f"""
+                INSERT INTO search_vector_chunks (
+                    entity_id,
+                    project_id,
+                    chunk_key,
+                    chunk_text,
+                    source_hash,
+                    entity_fingerprint,
+                    embedding_model,
+                    updated_at
+                ) VALUES {", ".join(upsert_values)}
+                ON CONFLICT (project_id, entity_id, chunk_key) DO UPDATE SET
+                    chunk_text = EXCLUDED.chunk_text,
+                    source_hash = EXCLUDED.source_hash,
+                    entity_fingerprint = EXCLUDED.entity_fingerprint,
+                    embedding_model = EXCLUDED.embedding_model,
+                    updated_at = NOW()
+                RETURNING id, chunk_key
+            """),
+            upsert_params,
+        )
+        upserted_ids_by_key = {
+            str(row["chunk_key"]): int(row["id"]) for row in upsert_result.mappings().all()
+        }
+        return [
+            (upserted_ids_by_key[record["chunk_key"]], record["chunk_text"])
+            for record in scheduled_records
+        ]
+
     async def _write_embeddings(
         self,
         session: AsyncSession,
         jobs: list[tuple[int, str]],
         embeddings: list[list[float]],
     ) -> None:
-        for (row_id, _), vector in zip(jobs, embeddings, strict=True):
-            vector_literal = self._format_pgvector_literal(vector)
-            await session.execute(
-                text(
-                    "INSERT INTO search_vector_embeddings ("
-                    "chunk_id, project_id, embedding, embedding_dims, updated_at"
-                    ") VALUES ("
-                    ":chunk_id, :project_id, CAST(:embedding AS vector), :embedding_dims, NOW()"
-                    ") "
-                    "ON CONFLICT (chunk_id) DO UPDATE SET "
-                    "project_id = EXCLUDED.project_id, "
-                    "embedding = EXCLUDED.embedding, "
-                    "embedding_dims = EXCLUDED.embedding_dims, "
-                    "updated_at = NOW()"
-                ),
-                {
-                    "chunk_id": row_id,
-                    "project_id": self.project_id,
-                    "embedding": vector_literal,
-                    "embedding_dims": len(vector),
-                },
+        params: dict[str, object] = {"project_id": self.project_id}
+        value_rows: list[str] = []
+
+        # The SQL template is built from integer enumerate() indices only.
+        # No user-controlled text is interpolated into the statement.
+        for index, ((row_id, _), vector) in enumerate(zip(jobs, embeddings, strict=True)):
+            params[f"chunk_id_{index}"] = row_id
+            params[f"embedding_{index}"] = self._format_pgvector_literal(vector)
+            params[f"embedding_dims_{index}"] = len(vector)
+            value_rows.append(
+                "("
+                f":chunk_id_{index}, :project_id, CAST(:embedding_{index} AS vector), "
+                f":embedding_dims_{index}, NOW()"
+                ")"
             )
 
+        await session.execute(
+            text(f"""
+                INSERT INTO search_vector_embeddings (
+                    chunk_id,
+                    project_id,
+                    embedding,
+                    embedding_dims,
+                    updated_at
+                ) VALUES {", ".join(value_rows)}
+                ON CONFLICT (chunk_id) DO UPDATE SET
+                    project_id = EXCLUDED.project_id,
+                    embedding = EXCLUDED.embedding,
+                    embedding_dims = EXCLUDED.embedding_dims,
+                    updated_at = NOW()
+            """),
+            params,
+        )
+
     async def _delete_entity_chunks(
         self,
         session: AsyncSession,
@@ -506,9 +598,6 @@ class PostgresSearchRepository(SearchRepositoryBase):
             stale_params,
         )
 
-    async def _update_timestamp_sql(self) -> str:
-        return "NOW()"  # pragma: no cover
-
     def _distance_to_similarity(self, distance: float) -> float:
         """Convert pgvector cosine distance to cosine similarity.
 

src/basic_memory/repository/repository.py

@@ -268,21 +268,8 @@ class Repository[T: Base]:
 
             return await self.select_by_ids(session, [model.id for model in model_list])  # pyright: ignore [reportAttributeAccessIssue]
 
-    async def update(
-        self,
-        entity_id: int,
-        entity_data: dict | T,
-        *,
-        reload: bool = True,
-    ) -> Optional[T]:
-        """Update an entity with the given data.
-
-        Args:
-            entity_id: Primary key to update
-            entity_data: Column values or a model instance to copy from
-            reload: When True, re-select the entity with repository load options.
-                When False, return the attached row after flush/refresh.
-        """
+    async def update(self, entity_id: int, entity_data: dict[str, Any] | T) -> Optional[T]:
+        """Update an entity with the given data."""
         logger.debug(f"Updating {self.Model.__name__} {entity_id} with data: {entity_data}")
         async with db.scoped_session(self.session_maker) as session:
             try:
@@ -292,20 +279,19 @@ class Repository[T: Base]:
                 entity = result.scalars().one()
 
                 if isinstance(entity_data, dict):
-                    for key, value in entity_data.items():
+                    update_data = cast(dict[str, Any], entity_data)
+                    for key, value in update_data.items():
                         if key in self.valid_columns:
                             setattr(entity, key, value)
 
                 elif isinstance(entity_data, self.Model):
-                    for column in self.Model.__table__.columns.keys():
+                    for column in self.valid_columns:
                         setattr(entity, column, getattr(entity_data, column))
 
                 await session.flush()  # Make sure changes are flushed
                 await session.refresh(entity)  # Refresh
 
                 logger.debug(f"Updated {self.Model.__name__}: {entity_id}")
-                if not reload:
-                    return entity
                 return await self.select_by_id(session, entity.id)  # pyright: ignore [reportAttributeAccessIssue]
 
             except NoResultFound:

src/basic_memory/repository/search_repository.py

@@ -70,6 +70,10 @@ class SearchRepository(Protocol):
         """Sync semantic vector chunks for an entity."""
         ...
 
+    async def delete_entity_vector_rows(self, entity_id: int) -> None:
+        """Delete semantic vector chunks and embeddings for one entity."""
+        ...
+
     async def sync_entity_vectors_batch(
         self,
         entity_ids: list[int],

src/basic_memory/repository/sqlite_search_repository.py

@@ -1,11 +1,11 @@
 """SQLite FTS5-based search repository implementation."""
 
+import asyncio
 import json
 import re
+from contextlib import asynccontextmanager
 from datetime import datetime
 from typing import List, Optional
-
-import asyncio
 from loguru import logger
 from sqlalchemy import text
 from sqlalchemy.exc import OperationalError as SAOperationalError
@@ -56,7 +56,8 @@ class SQLiteSearchRepository(SearchRepositoryBase):
             self._app_config.semantic_embedding_sync_batch_size
         )
         self._embedding_provider = embedding_provider
-        self._sqlite_vec_lock = asyncio.Lock()
+        self._sqlite_vec_load_lock = asyncio.Lock()
+        self._sqlite_prepare_write_lock = asyncio.Lock()
         self._vector_tables_initialized = False
         self._vector_dimensions = 384
 
@@ -349,7 +350,7 @@ class SQLiteSearchRepository(SearchRepositoryBase):
             pass
 
         try:
-            import sqlite_vec  # type: ignore[import-not-found]
+            import sqlite_vec
         except ImportError as exc:
             raise SemanticDependenciesMissingError(
                 "sqlite-vec package is missing. "
@@ -357,7 +358,13 @@ class SQLiteSearchRepository(SearchRepositoryBase):
                 "pip install -U basic-memory"
             ) from exc
 
-        async with self._sqlite_vec_lock:
+        # Trigger: sqlite-vec must be loaded on each SQLite connection before
+        # vec tables and functions are visible.
+        # Why: extension loading is connection-local, so we need one narrow
+        # critical section to avoid racing two coroutines on the same step.
+        # Outcome: connection setup stays serialized without blocking unrelated
+        # prepare work behind the write-side lock.
+        async with self._sqlite_vec_load_lock:
             try:
                 await session.execute(text("SELECT vec_version()"))
                 return
@@ -398,10 +405,16 @@ class SQLiteSearchRepository(SearchRepositoryBase):
                 "chunk_key",
                 "chunk_text",
                 "source_hash",
+                "entity_fingerprint",
+                "embedding_model",
                 "updated_at",
             }
             schema_mismatch = bool(chunks_columns) and set(chunks_columns) != expected_columns
             if schema_mismatch:
+                # Trigger: older SQLite installs are missing newly required chunk metadata columns.
+                # Why: vector tables store derived data only, so rebuilding them is safer than
+                # attempting piecemeal ALTER TABLE compatibility across sqlite-vec upgrades.
+                # Outcome: first startup after the schema change forces a clean re-embed.
                 logger.warning("search_vector_chunks schema mismatch, recreating vector tables")
                 await session.execute(text("DROP TABLE IF EXISTS search_vector_embeddings"))
                 await session.execute(text("DROP TABLE IF EXISTS search_vector_chunks"))
@@ -552,8 +565,60 @@ class SQLiteSearchRepository(SearchRepositoryBase):
             stale_params,
         )
 
-    async def _update_timestamp_sql(self) -> str:
-        return "CURRENT_TIMESTAMP"  # pragma: no cover
+    async def delete_project_vector_rows(self) -> None:
+        """Delete all vector rows for this project on a sqlite-vec-enabled connection."""
+        await self._ensure_vector_tables()
+
+        async with db.scoped_session(self.session_maker) as session:
+            await self._ensure_sqlite_vec_loaded(session)
+
+            # Constraint: sqlite-vec stores embeddings separately with no cascade delete.
+            # Why: full rebuild must clear embeddings before chunk rows or stale vectors remain.
+            # Outcome: the next sync recreates the project's derived vectors from scratch.
+            await session.execute(
+                text(
+                    "DELETE FROM search_vector_embeddings WHERE rowid IN ("
+                    "SELECT id FROM search_vector_chunks WHERE project_id = :project_id)"
+                ),
+                {"project_id": self.project_id},
+            )
+            await session.execute(
+                text("DELETE FROM search_vector_chunks WHERE project_id = :project_id"),
+                {"project_id": self.project_id},
+            )
+            await session.commit()
+
+    async def delete_stale_vector_rows(self) -> None:
+        """Delete vector rows whose source entities no longer exist."""
+        await self._ensure_vector_tables()
+
+        async with db.scoped_session(self.session_maker) as session:
+            await self._ensure_sqlite_vec_loaded(session)
+
+            stale_entity_filter = (
+                "entity_id NOT IN (SELECT id FROM entity WHERE project_id = :project_id)"
+            )
+            params = {"project_id": self.project_id}
+
+            # Trigger: deleted entities left behind derived vector rows.
+            # Why: sqlite-vec does not provide cascade cleanup from our chunk table.
+            # Outcome: stale vector state disappears before coverage stats or reindex runs.
+            await session.execute(
+                text(
+                    "DELETE FROM search_vector_embeddings WHERE rowid IN ("
+                    "SELECT id FROM search_vector_chunks "
+                    f"WHERE project_id = :project_id AND {stale_entity_filter})"
+                ),
+                params,
+            )
+            await session.execute(
+                text(
+                    "DELETE FROM search_vector_chunks "
+                    f"WHERE project_id = :project_id AND {stale_entity_filter}"
+                ),
+                params,
+            )
+            await session.commit()
 
     def _distance_to_similarity(self, distance: float) -> float:
         """Convert L2 distance to cosine similarity for normalized embeddings.
@@ -563,13 +628,26 @@ class SQLiteSearchRepository(SearchRepositoryBase):
         """
         return max(0.0, 1.0 - (distance * distance) / 2.0)
 
-    def _orphan_detection_sql(self) -> str:
-        """SQLite sqlite-vec uses rowid-based embedding table."""
+    @asynccontextmanager
+    async def _prepare_entity_write_scope(self):
+        """SQLite keeps the shared read window, but funnels prepare writes through one lock."""
+        # Trigger: the shared prepare window fans out per entity after batched reads.
+        # Why: SQLite still benefits from shared reads, but write transactions do
+        # not get meaningfully faster when we open many at once.
+        # Outcome: one entity at a time mutates chunk rows, while vec extension
+        # loading uses its own separate lock and cannot deadlock this path.
+        async with self._sqlite_prepare_write_lock:
+            yield
+
+    def _prepare_window_existing_rows_sql(self, placeholders: str) -> str:
+        """SQLite sqlite-vec stores embeddings by rowid rather than chunk_id."""
         return (
-            "SELECT c.id FROM search_vector_chunks c "
+            "SELECT c.entity_id, c.id, c.chunk_key, c.source_hash, c.entity_fingerprint, "
+            "c.embedding_model, (e.rowid IS NOT NULL) AS has_embedding "
+            "FROM search_vector_chunks c "
             "LEFT JOIN search_vector_embeddings e ON e.rowid = c.id "
-            "WHERE c.project_id = :project_id AND c.entity_id = :entity_id "
-            "AND e.rowid IS NULL"
+            f"WHERE c.project_id = :project_id AND c.entity_id IN ({placeholders}) "
+            "ORDER BY c.entity_id ASC, c.chunk_key ASC"
         )
 
     # ------------------------------------------------------------------

src/basic_memory/schemas/cloud.py

@@ -81,3 +81,53 @@ class WorkspaceListResponse(BaseModel):
     current_workspace_id: str | None = Field(
         default=None, description="Current workspace tenant ID when available"
     )
+
+
+class CloudProjectIndexStatus(BaseModel):
+    """Index freshness summary for one cloud project."""
+
+    project_name: str = Field(..., description="Project name")
+    project_id: int = Field(..., description="Project database identifier")
+    last_scan_timestamp: float | None = Field(
+        default=None, description="Last scan timestamp from project metadata"
+    )
+    last_file_count: int | None = Field(default=None, description="Last observed file count")
+    current_file_count: int = Field(..., description="Current markdown file count")
+    total_entities: int = Field(..., description="Current markdown entity count")
+    total_note_content_rows: int = Field(..., description="Rows present in note_content")
+    note_content_synced: int = Field(..., description="Files fully materialized into note_content")
+    note_content_pending: int = Field(..., description="Pending note_content rows")
+    note_content_failed: int = Field(..., description="Failed note_content rows")
+    note_content_external_changes: int = Field(
+        ..., description="Rows flagged with external file changes"
+    )
+    total_indexed_entities: int = Field(..., description="Files represented in search_index")
+    embedding_opt_out_entities: int = Field(..., description="Files opted out of vector embeddings")
+    embeddable_indexed_entities: int = Field(
+        ..., description="Indexed files eligible for vector embeddings"
+    )
+    total_entities_with_chunks: int = Field(..., description="Embeddable files with vector chunks")
+    total_chunks: int = Field(..., description="Vector chunk row count")
+    total_embeddings: int = Field(..., description="Vector embedding row count")
+    orphaned_chunks: int = Field(..., description="Chunks missing embeddings")
+    vector_tables_exist: bool = Field(..., description="Whether vector tables exist")
+    materialization_current: bool = Field(
+        ..., description="Whether note content matches the current file set"
+    )
+    search_current: bool = Field(..., description="Whether search coverage is current")
+    embeddings_current: bool = Field(..., description="Whether embedding coverage is current")
+    project_current: bool = Field(..., description="Whether all freshness checks are current")
+    reindex_recommended: bool = Field(..., description="Whether a reindex is recommended")
+    reindex_reason: str | None = Field(default=None, description="Reason a reindex is recommended")
+
+
+class CloudTenantIndexStatusResponse(BaseModel):
+    """Index freshness summary for all projects in one cloud tenant."""
+
+    tenant_id: str = Field(..., description="Workspace tenant identifier")
+    fly_app_name: str = Field(..., description="Cloud tenant application identifier")
+    email: str | None = Field(default=None, description="Owner email when available")
+    projects: list[CloudProjectIndexStatus] = Field(
+        default_factory=list, description="Per-project freshness summaries"
+    )
+    error: str | None = Field(default=None, description="Tenant-level lookup error")

src/basic_memory/schemas/memory.py

@@ -103,7 +103,7 @@ MemoryUrl = Annotated[
 memory_url = TypeAdapter(MemoryUrl)
 
 
-def memory_url_path(url: memory_url) -> str:  # pyright: ignore
+def memory_url_path(url: str) -> str:
     """
     Returns the uri for a url value by removing the prefix "memory://" from a given MemoryUrl.
 

src/basic_memory/schemas/response.py

@@ -194,7 +194,7 @@ class EntityResponse(SQLAlchemyModel):
     note_type: NoteType
 
     # COMPAT(v0.18): old clients expect entity_type; remove when no longer needed
-    @computed_field  # type: ignore[prop-decorator]
+    @computed_field
     @property
     def entity_type(self) -> str:
         return self.note_type

src/basic_memory/services/entity_service.py

@@ -60,6 +60,11 @@ class EntityWriteResult:
     search_content: str
 
 
+def _frontmatter_permalink(value: object) -> str | None:
+    """Return an explicit frontmatter permalink only when YAML parsed a real string."""
+    return value if isinstance(value, str) and value else None
+
+
 class EntityService(BaseService[EntityModel]):
     """Service for managing entities in the database."""
 
@@ -287,9 +292,13 @@ class EntityService(BaseService[EntityModel]):
                 schema.note_type = content_frontmatter["type"]
 
             if "permalink" in content_frontmatter:
-                content_markdown = self._build_frontmatter_markdown(
-                    schema.title, schema.note_type, content_frontmatter["permalink"]
-                )
+                content_permalink = _frontmatter_permalink(content_frontmatter["permalink"])
+                if content_permalink is not None:
+                    content_markdown = self._build_frontmatter_markdown(
+                        schema.title,
+                        schema.note_type,
+                        content_permalink,
+                    )
 
         # Get unique permalink (prioritizing content frontmatter) unless disabled
         if self.app_config and self.app_config.disable_permalinks:
@@ -332,14 +341,17 @@ class EntityService(BaseService[EntityModel]):
             action="create",
             phase="upsert_entity",
         ):
-            updated = await self.upsert_entity_from_markdown(
-                file_path,
-                entity_markdown,
-                is_new=True,
-                checksum=checksum,
-            )
+            entity = await self.upsert_entity_from_markdown(file_path, entity_markdown, is_new=True)
+
+        with telemetry.scope(
+            "entity_service.create.update_checksum",
+            domain="entity_service",
+            action="create",
+            phase="update_checksum",
+        ):
+            updated = await self.repository.update(entity.id, {"checksum": checksum})
         if not updated:  # pragma: no cover
-            raise ValueError(f"Failed to persist entity after create: {file_path}")
+            raise ValueError(f"Failed to update entity checksum after create: {entity.id}")
         return EntityWriteResult(
             entity=updated,
             content=final_content,
@@ -389,9 +401,13 @@ class EntityService(BaseService[EntityModel]):
                 schema.note_type = content_frontmatter["type"]
 
             if "permalink" in content_frontmatter:
-                content_markdown = self._build_frontmatter_markdown(
-                    schema.title, schema.note_type, content_frontmatter["permalink"]
-                )
+                content_permalink = _frontmatter_permalink(content_frontmatter["permalink"])
+                if content_permalink is not None:
+                    content_markdown = self._build_frontmatter_markdown(
+                        schema.title,
+                        schema.note_type,
+                        content_permalink,
+                    )
 
         # Check if we need to update the permalink based on content frontmatter (unless disabled)
         new_permalink = entity.permalink  # Default to existing
@@ -456,13 +472,18 @@ class EntityService(BaseService[EntityModel]):
             phase="upsert_entity",
         ):
             entity = await self.upsert_entity_from_markdown(
-                file_path,
-                entity_markdown,
-                is_new=False,
-                checksum=checksum,
+                file_path, entity_markdown, is_new=False
             )
+
+        with telemetry.scope(
+            "entity_service.update.update_checksum",
+            domain="entity_service",
+            action="update",
+            phase="update_checksum",
+        ):
+            entity = await self.repository.update(entity.id, {"checksum": checksum})
         if not entity:  # pragma: no cover
-            raise ValueError(f"Failed to persist entity after update: {file_path}")
+            raise ValueError(f"Failed to update entity checksum after update: {file_path}")
 
         return EntityWriteResult(
             entity=entity,
@@ -513,9 +534,13 @@ class EntityService(BaseService[EntityModel]):
                 schema.note_type = content_frontmatter["type"]
 
             if "permalink" in content_frontmatter:
-                content_markdown = self._build_frontmatter_markdown(
-                    schema.title, schema.note_type, content_frontmatter["permalink"]
-                )
+                content_permalink = _frontmatter_permalink(content_frontmatter["permalink"])
+                if content_permalink is not None:
+                    content_markdown = self._build_frontmatter_markdown(
+                        schema.title,
+                        schema.note_type,
+                        content_permalink,
+                    )
 
         # --- Permalink Resolution ---
         if self.app_config and self.app_config.disable_permalinks:
@@ -654,11 +679,13 @@ class EntityService(BaseService[EntityModel]):
                 update_data["note_type"] = _coerce_to_string(content_frontmatter["type"])
 
             if "permalink" in content_frontmatter:
-                content_markdown = self._build_frontmatter_markdown(
-                    update_data.get("title", entity.title),
-                    update_data.get("note_type", entity.note_type),
-                    content_frontmatter["permalink"],
-                )
+                content_permalink = _frontmatter_permalink(content_frontmatter["permalink"])
+                if content_permalink is not None:
+                    content_markdown = self._build_frontmatter_markdown(
+                        _coerce_to_string(update_data.get("title", entity.title)),
+                        _coerce_to_string(update_data.get("note_type", entity.note_type)),
+                        content_permalink,
+                    )
 
             metadata = normalize_frontmatter_metadata(content_frontmatter or {})
             update_data["entity_metadata"] = {k: v for k, v in metadata.items() if v is not None}
@@ -848,7 +875,7 @@ class EntityService(BaseService[EntityModel]):
 
         # Use UPSERT to handle conflicts cleanly
         try:
-            return await self.repository.upsert_entity(model, reload=False)
+            return await self.repository.upsert_entity(model)
         except Exception as e:
             logger.error(f"Failed to upsert entity for {file_path}: {e}")
             raise EntityCreationError(f"Failed to create entity: {str(e)}") from e
@@ -863,15 +890,22 @@ class EntityService(BaseService[EntityModel]):
         """
         logger.debug(f"Updating entity and observations: {file_path}")
 
-        db_entity = await self.repository.get_by_file_path(
-            file_path.as_posix(),
-            load_relations=False,
-        )
-        if not db_entity:  # pragma: no cover
-            raise EntityNotFoundError(f"Entity not found: {file_path}")
+        with telemetry.scope(
+            "upsert.update.fetch_entity",
+            domain="entity_service",
+            action="upsert",
+            phase="fetch_entity",
+        ):
+            db_entity = await self.repository.get_by_file_path(file_path.as_posix())
 
         # Clear observations for entity
-        await self.observation_repository.delete_by_fields(entity_id=db_entity.id)
+        with telemetry.scope(
+            "upsert.update.delete_observations",
+            domain="entity_service",
+            action="upsert",
+            phase="delete_observations",
+        ):
+            await self.observation_repository.delete_by_fields(entity_id=db_entity.id)
 
         # add new observations
         observations = [
@@ -885,38 +919,37 @@ class EntityService(BaseService[EntityModel]):
             )
             for obs in markdown.observations
         ]
-        if observations:
+        with telemetry.scope(
+            "upsert.update.insert_observations",
+            domain="entity_service",
+            action="upsert",
+            phase="insert_observations",
+            count=len(observations),
+        ):
             await self.observation_repository.add_all(observations)
 
-        # Trigger: the lightweight lookup above returns a detached row without loaded collections
-        # Why: assigning a new observation list onto that detached ORM object would trigger lazy loads
-        # Outcome: rebuild a fresh model from markdown, then copy over stable identity fields
-        db_entity_data = entity_model_from_markdown(
-            file_path,
-            markdown,
-            project_id=self.repository.project_id,
-        )
-        db_entity_data.id = db_entity.id
-        db_entity_data.project_id = db_entity.project_id
-        db_entity_data.external_id = db_entity.external_id
-        db_entity_data.created_by = db_entity.created_by
+        # update values from markdown
+        db_entity = entity_model_from_markdown(file_path, markdown, db_entity)
 
         # checksum value is None == not finished with sync
-        db_entity_data.checksum = None
+        db_entity.checksum = None
 
         # Set last_updated_by for cloud usage (preserve existing created_by)
         user_id = self.get_user_id()
         if user_id is not None:
-            db_entity_data.last_updated_by = user_id
-        else:
-            db_entity_data.last_updated_by = db_entity.last_updated_by
+            db_entity.last_updated_by = user_id
 
         # update entity
-        return await self.repository.update(
-            db_entity.id,
-            db_entity_data,
-            reload=False,
-        )
+        with telemetry.scope(
+            "upsert.update.save_entity",
+            domain="entity_service",
+            action="upsert",
+            phase="save_entity",
+        ):
+            return await self.repository.update(
+                db_entity.id,
+                db_entity,
+            )
 
     async def upsert_entity_from_markdown(
         self,
@@ -924,76 +957,36 @@ class EntityService(BaseService[EntityModel]):
         markdown: EntityMarkdown,
         *,
         is_new: bool,
-        checksum: Optional[str] = None,
     ) -> EntityModel:
         """Create/update entity and relations from parsed markdown."""
-        # --- Base Entity Row ---
-        # Trigger: writes rebuild the entity row before touching relation edges
-        # Why: relations need a stable source entity ID, but not a fully hydrated graph
-        # Outcome: create/update the row with a lightweight return value
-        with telemetry.scope(
-            "entity_service.upsert.base_entity",
-            domain="entity_service",
-            action="upsert",
-            phase="base_entity",
-        ):
-            if is_new:
-                created = await self.create_entity_from_markdown(file_path, markdown)
-            else:
-                created = await self.update_entity_and_observations(file_path, markdown)
-
-        # --- Relation Edges ---
-        with telemetry.scope(
-            "entity_service.upsert.relations",
-            domain="entity_service",
-            action="upsert",
-            phase="relations",
-        ):
-            await self.update_entity_relations(created, markdown)
-
-        # --- Final Entity State ---
-        # Trigger: create/update/edit already computed the final file checksum
-        # Why: fold the checksum write into the upsert flow so callers do one hydrated read
-        # Outcome: the write path returns the final entity state without an extra checksum step
-        if checksum is not None:
-            with telemetry.scope(
-                "entity_service.upsert.persist_checksum",
-                domain="entity_service",
-                action="upsert",
-                phase="persist_checksum",
-            ):
-                updated = await self.repository.update(created.id, {"checksum": checksum})
-            if not updated:  # pragma: no cover
-                raise ValueError(f"Failed to update entity checksum after upsert: {file_path}")
-            return updated
-
-        with telemetry.scope(
-            "entity_service.upsert.hydrate_entity",
-            domain="entity_service",
-            action="upsert",
-            phase="hydrate_entity",
-        ):
-            hydrated = await self.repository.get_by_file_path(created.file_path)
-        if not hydrated:  # pragma: no cover
-            raise EntityNotFoundError(f"Entity not found after upsert: {created.file_path}")
-        return hydrated
+        if is_new:
+            created = await self.create_entity_from_markdown(file_path, markdown)
+        else:
+            created = await self.update_entity_and_observations(file_path, markdown)
+        # Pass entity directly — avoids redundant get_by_file_path inside update_entity_relations
+        return await self.update_entity_relations(created, markdown)
 
     async def update_entity_relations(
         self,
-        db_entity: EntityModel,
+        entity: EntityModel,
         markdown: EntityMarkdown,
-    ) -> None:
-        """Update relations for entity"""
-        logger.debug(f"Updating relations for entity: {db_entity.file_path}")
+    ) -> EntityModel:
+        """Update relations for entity.
+
+        Accepts the entity object directly to avoid a redundant DB fetch.
+        Only entity.id and entity.permalink are used from the passed-in object.
+        """
+        entity_id = entity.id
+        logger.debug(f"Updating relations for entity: {entity.file_path}")
 
         # Clear existing relations first
         with telemetry.scope(
-            "entity_service.upsert.delete_relations",
+            "upsert.relations.delete_existing",
             domain="entity_service",
             action="upsert",
             phase="delete_relations",
         ):
-            await self.relation_repository.delete_outgoing_relations_from_entity(db_entity.id)
+            await self.relation_repository.delete_outgoing_relations_from_entity(entity_id)
 
         # Batch resolve all relation targets in parallel
         if markdown.relations:
@@ -1002,22 +995,23 @@ class EntityService(BaseService[EntityModel]):
             # Create tasks for all relation lookups
             # Use strict=True to disable fuzzy search - only exact matches should create resolved relations
             # This ensures forward references (links to non-existent entities) remain unresolved (to_id=NULL)
+            lookup_tasks = [
+                self.link_resolver.resolve_link(
+                    rel.target,
+                    strict=True,
+                    load_relations=False,
+                )
+                for rel in markdown.relations
+            ]
+
+            # Execute all lookups in parallel
             with telemetry.scope(
-                "entity_service.upsert.resolve_relation_targets",
+                "upsert.relations.resolve_links",
                 domain="entity_service",
                 action="upsert",
-                phase="resolve_relation_targets",
+                phase="resolve_links",
+                count=len(lookup_tasks),
             ):
-                lookup_tasks = [
-                    self.link_resolver.resolve_link(
-                        rel.target,
-                        strict=True,
-                        load_relations=False,
-                    )
-                    for rel in markdown.relations
-                ]
-
-                # Execute all lookups in parallel
                 resolved_entities = await asyncio.gather(*lookup_tasks, return_exceptions=True)
 
             # Process results and create relation records
@@ -1027,7 +1021,7 @@ class EntityService(BaseService[EntityModel]):
                 target_entity: Optional[Entity] = None
                 if not isinstance(resolved, Exception):
                     # Type narrowing: resolved is Optional[Entity] here, not Exception
-                    target_entity = resolved  # type: ignore
+                    target_entity = resolved
 
                 # if the target is found, store the id
                 target_id = target_entity.id if target_entity else None
@@ -1037,7 +1031,7 @@ class EntityService(BaseService[EntityModel]):
                 # Create the relation
                 relation = Relation(
                     project_id=self.relation_repository.project_id,
-                    from_id=db_entity.id,
+                    from_id=entity_id,
                     to_id=target_id,
                     to_name=target_name,
                     relation_type=rel.type,
@@ -1048,10 +1042,11 @@ class EntityService(BaseService[EntityModel]):
             # Batch insert all relations
             if relations_to_add:
                 with telemetry.scope(
-                    "entity_service.upsert.insert_relations",
+                    "upsert.relations.insert_relations",
                     domain="entity_service",
                     action="upsert",
                     phase="insert_relations",
+                    count=len(relations_to_add),
                 ):
                     try:
                         await self.relation_repository.add_all(relations_to_add)
@@ -1064,10 +1059,20 @@ class EntityService(BaseService[EntityModel]):
                             except IntegrityError:
                                 # Unique constraint violation - relation already exists
                                 logger.debug(
-                                    f"Skipping duplicate relation {relation.relation_type} from {db_entity.permalink}"
+                                    f"Skipping duplicate relation {relation.relation_type} from {entity.permalink}"
                                 )
                                 continue
 
+        # Reload entity with relations via PK lookup (faster than get_by_file_path string match)
+        with telemetry.scope(
+            "upsert.relations.reload_entity",
+            domain="entity_service",
+            action="upsert",
+            phase="reload_entity",
+        ):
+            reloaded = await self.repository.find_by_ids([entity_id])
+        return reloaded[0]
+
     async def edit_entity(
         self,
         identifier: str,
@@ -1176,13 +1181,18 @@ class EntityService(BaseService[EntityModel]):
             phase="upsert_entity",
         ):
             entity = await self.upsert_entity_from_markdown(
-                file_path,
-                entity_markdown,
-                is_new=False,
-                checksum=checksum,
+                file_path, entity_markdown, is_new=False
             )
+
+        with telemetry.scope(
+            "entity_service.edit.update_checksum",
+            domain="entity_service",
+            action="edit",
+            phase="update_checksum",
+        ):
+            entity = await self.repository.update(entity.id, {"checksum": checksum})
         if not entity:  # pragma: no cover
-            raise ValueError(f"Failed to persist entity after edit: {file_path}")
+            raise ValueError(f"Failed to update entity checksum after edit: {file_path}")
 
         return EntityWriteResult(
             entity=entity,

src/basic_memory/services/file_service.py

@@ -3,6 +3,7 @@
 import asyncio
 import hashlib
 import mimetypes
+from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple, Union
@@ -25,6 +26,14 @@ from basic_memory.utils import FilePath
 from loguru import logger
 
 
+@dataclass(slots=True)
+class FrontmatterUpdateResult:
+    """Final content emitted by a frontmatter rewrite without a follow-up reread."""
+
+    checksum: str
+    content: str
+
+
 class FileService:
     """Service for handling file operations with concurrency control.
 
@@ -199,15 +208,20 @@ class FileService:
 
                 await file_utils.write_file_atomic(full_path, content)
 
-                final_content = content
                 if self.app_config:
                     formatted_content = await file_utils.format_file(
                         full_path, self.app_config, is_markdown=self.is_markdown(path)
                     )
                     if formatted_content is not None:
-                        final_content = formatted_content  # pragma: no cover
+                        pass  # pragma: no cover
 
-                checksum = await file_utils.compute_checksum(final_content)
+                # Trigger: formatters and platform-specific text writers can change the
+                # persisted bytes even when the logical content string is the same.
+                # Why: sync and move detection compare against on-disk checksums, not
+                #      the pre-write Python string.
+                # Outcome: return the checksum of the actual stored file so callers do
+                #          not record a hash that immediately disagrees with the file.
+                checksum = await self.compute_checksum(full_path)
                 logger.debug(f"File write completed path={full_path}, {checksum=}")
                 return checksum
 
@@ -301,7 +315,7 @@ class FileService:
 
         except Exception as e:
             logger.exception("File read error", path=str(full_path), error=str(e))
-            raise FileOperationError(f"Failed to read file: {e}")
+            raise FileOperationError(f"Failed to read file: {e}") from e
 
     async def read_file(self, path: FilePath) -> Tuple[str, str]:
         """Read file and compute checksum using true async I/O.
@@ -336,7 +350,13 @@ class FileService:
                 async with aiofiles.open(full_path, mode="r", encoding="utf-8") as f:
                     content = await f.read()
 
-                checksum = await file_utils.compute_checksum(content)
+                # Trigger: text-mode reads normalize line endings on Windows, so the
+                #          decoded string can differ from the bytes we just wrote.
+                # Why: write_file/update_frontmatter now return the checksum of the
+                #      persisted file, and read_file should report the same authority.
+                # Outcome: callers get human-readable content plus the checksum for the
+                #          exact bytes stored on disk.
+                checksum = await self.compute_checksum(full_path)
 
                 logger.debug(
                     "File read completed",
@@ -401,12 +421,14 @@ class FileService:
             )
             raise FileOperationError(f"Failed to move file {source} -> {destination}: {e}")
 
-    async def update_frontmatter(self, path: FilePath, updates: Dict[str, Any]) -> str:
-        """Update frontmatter fields in a file while preserving all content.
+    async def update_frontmatter_with_result(
+        self, path: FilePath, updates: Dict[str, Any]
+    ) -> FrontmatterUpdateResult:
+        """Update frontmatter and return the exact final written markdown content.
 
         Only modifies the frontmatter section, leaving all content untouched.
         Creates frontmatter section if none exists.
-        Returns checksum of updated file.
+        Returns both checksum and final content so callers do not need a reread.
 
         Uses aiofiles for true async I/O (non-blocking).
 
@@ -415,7 +437,7 @@ class FileService:
             updates: Dict of frontmatter fields to update
 
         Returns:
-            Checksum of updated file
+            Typed result containing checksum and final content
 
         Raises:
             FileOperationError: If file operations fail
@@ -467,7 +489,14 @@ class FileService:
                 if formatted_content is not None:
                     content_for_checksum = formatted_content  # pragma: no cover
 
-            return await file_utils.compute_checksum(content_for_checksum)
+            # Trigger: frontmatter normalization may persist bytes that differ from the
+            # in-memory string because of formatter output or platform newline handling.
+            # Why: follow-up scans and checksum-based move detection read raw bytes from disk.
+            # Outcome: the returned checksum always matches the file that was just written.
+            return FrontmatterUpdateResult(
+                checksum=await self.compute_checksum(full_path),
+                content=content_for_checksum,
+            )
 
         except Exception as e:  # pragma: no cover
             # Only log real errors (not YAML parsing, which is handled above)
@@ -479,6 +508,11 @@ class FileService:
                 )
             raise FileOperationError(f"Failed to update frontmatter: {e}")
 
+    async def update_frontmatter(self, path: FilePath, updates: Dict[str, Any]) -> str:
+        """Update frontmatter fields in a file while preserving all content."""
+        result = await self.update_frontmatter_with_result(path, updates)
+        return result.checksum
+
     async def compute_checksum(self, path: FilePath) -> str:
         """Compute checksum for a file using true async I/O.
 

src/basic_memory/services/link_resolver.py

@@ -72,7 +72,10 @@ class LinkResolver:
         # UUIDs also match the stored external_id values.
         try:
             canonical_id = str(uuid_mod.UUID(clean_text))
-            entity = await self.entity_repository.get_by_external_id(canonical_id)
+            entity = await self.entity_repository.get_by_external_id(
+                canonical_id,
+                load_relations=load_relations,
+            )
             if entity:
                 logger.debug(f"Found entity by external_id: {entity.permalink}")
                 return entity

src/basic_memory/services/search_service.py

@@ -1,5 +1,6 @@
 """Service for search operations."""
 
+import asyncio
 import ast
 import re
 from datetime import datetime
@@ -427,6 +428,15 @@ class SearchService:
 
     async def sync_entity_vectors(self, entity_id: int) -> None:
         """Refresh vector chunks for one entity in repositories that support semantic indexing."""
+        entity = await self.entity_repository.find_by_id(entity_id)
+        if entity is None:
+            await self._clear_entity_vectors(entity_id)
+            return
+
+        if not self._entity_embeddings_enabled(entity):
+            await self._clear_entity_vectors(entity_id)
+            return
+
         await self.repository.sync_entity_vectors(entity_id)
 
     async def sync_entity_vectors_batch(
@@ -435,16 +445,101 @@ class SearchService:
         progress_callback=None,
     ) -> VectorSyncBatchResult:
         """Refresh vector chunks for a batch of entities."""
-        return await self.repository.sync_entity_vectors_batch(
-            entity_ids,
-            progress_callback=progress_callback,
-        )
+        if not entity_ids:
+            return VectorSyncBatchResult(
+                entities_total=0,
+                entities_synced=0,
+                entities_failed=0,
+            )
 
-    async def reindex_vectors(self, progress_callback=None) -> dict:
+        entities_by_id = {
+            entity.id: entity for entity in await self.entity_repository.find_by_ids(entity_ids)
+        }
+        unknown_ids = [entity_id for entity_id in entity_ids if entity_id not in entities_by_id]
+        opted_out_ids = [
+            entity_id
+            for entity_id in entity_ids
+            if (
+                (entity := entities_by_id.get(entity_id)) is not None
+                and not self._entity_embeddings_enabled(entity)
+            )
+        ]
+        if opted_out_ids:
+            await asyncio.gather(
+                *(self._clear_entity_vectors(entity_id) for entity_id in opted_out_ids)
+            )
+
+        eligible_entity_ids = [
+            entity_id
+            for entity_id in entity_ids
+            if entity_id in entities_by_id and entity_id not in opted_out_ids
+        ]
+
+        cleanup_task = (
+            self.repository.sync_entity_vectors_batch(unknown_ids) if unknown_ids else None
+        )
+        eligible_task = (
+            self.repository.sync_entity_vectors_batch(
+                eligible_entity_ids,
+                progress_callback=progress_callback,
+            )
+            if eligible_entity_ids
+            else None
+        )
+        repository_results = [
+            result
+            for result in await asyncio.gather(
+                cleanup_task if cleanup_task is not None else asyncio.sleep(0, result=None),
+                eligible_task if eligible_task is not None else asyncio.sleep(0, result=None),
+            )
+            if result is not None
+        ]
+
+        if not repository_results:
+            return VectorSyncBatchResult(
+                entities_total=len(entity_ids),
+                entities_synced=0,
+                entities_failed=0,
+                entities_skipped=len(opted_out_ids),
+            )
+
+        batch_result = VectorSyncBatchResult(
+            entities_total=len(entity_ids),
+            entities_synced=sum(result.entities_synced for result in repository_results),
+            entities_failed=sum(result.entities_failed for result in repository_results),
+            entities_deferred=sum(result.entities_deferred for result in repository_results),
+            entities_skipped=(
+                len(opted_out_ids)
+                + sum(result.entities_skipped for result in repository_results)
+                - len(unknown_ids)
+            ),
+            failed_entity_ids=[
+                failed_entity_id
+                for result in repository_results
+                for failed_entity_id in result.failed_entity_ids
+            ],
+            chunks_total=sum(result.chunks_total for result in repository_results),
+            chunks_skipped=sum(result.chunks_skipped for result in repository_results),
+            embedding_jobs_total=sum(result.embedding_jobs_total for result in repository_results),
+            prepare_seconds_total=sum(
+                result.prepare_seconds_total for result in repository_results
+            ),
+            queue_wait_seconds_total=sum(
+                result.queue_wait_seconds_total for result in repository_results
+            ),
+            embed_seconds_total=sum(result.embed_seconds_total for result in repository_results),
+            write_seconds_total=sum(result.write_seconds_total for result in repository_results),
+        )
+        return batch_result
+
+    async def reindex_vectors(self, progress_callback=None, force_full: bool = False) -> dict:
         """Rebuild vector embeddings for all entities.
 
         Args:
-            progress_callback: Optional callable(entity_id, index, total) for progress reporting.
+            progress_callback: Optional callable(entity_id, completed, total) for progress
+                reporting when an entity reaches a terminal state in this run.
+            force_full: When True, clear this project's derived vectors first so every
+                eligible entity re-embeds from scratch.
 
         Returns:
             dict with stats: total_entities, embedded, skipped, errors
@@ -455,15 +550,17 @@ class SearchService:
         # Clean up stale rows in search_index and search_vector_chunks
         # that reference entity_ids no longer in the entity table
         await self._purge_stale_search_rows()
+        if force_full:
+            await self._clear_project_vectors_for_full_reindex()
 
-        batch_result = await self.repository.sync_entity_vectors_batch(
+        batch_result = await self.sync_entity_vectors_batch(
             entity_ids,
             progress_callback=progress_callback,
         )
         stats = {
             "total_entities": batch_result.entities_total,
             "embedded": batch_result.entities_synced,
-            "skipped": 0,
+            "skipped": batch_result.entities_skipped,
             "errors": batch_result.entities_failed,
         }
 
@@ -472,6 +569,31 @@ class SearchService:
 
         return stats
 
+    async def _clear_project_vectors_for_full_reindex(self) -> None:
+        """Remove this project's derived vectors so a full reindex re-embeds everything.
+
+        Trigger: the operator asked for a full embedding rebuild rather than the
+        default incremental vector sync.
+        Why: the repository sync path intentionally skips unchanged entities, so
+        we need to clear the derived vector state first to force fresh embeddings.
+        Outcome: the next batch sync recreates every eligible entity's vectors.
+        """
+        from basic_memory.repository.sqlite_search_repository import SQLiteSearchRepository
+
+        project_id = self.repository.project_id
+        params = {"project_id": project_id}
+
+        # Constraint: sqlite-vec stores embeddings in a separate rowid table with
+        # no cascade delete, so embeddings must be removed before chunk rows.
+        if isinstance(self.repository, SQLiteSearchRepository):
+            await self.repository.delete_project_vector_rows()
+        else:
+            await self.repository.execute_query(
+                text("DELETE FROM search_vector_chunks WHERE project_id = :project_id"),
+                params,
+            )
+        logger.info("Cleared project vectors for full reindex", project_id=project_id)
+
     async def _purge_stale_search_rows(self) -> None:
         """Remove rows from search_index and search_vector_chunks for deleted entities.
 
@@ -498,26 +620,58 @@ class SearchService:
 
         # SQLite vec has no CASCADE — must delete embeddings before chunks
         if isinstance(self.repository, SQLiteSearchRepository):
+            await self.repository.delete_stale_vector_rows()
+        else:
+            # Postgres CASCADE handles embedding deletion automatically
             await self.repository.execute_query(
                 text(
-                    "DELETE FROM search_vector_embeddings WHERE rowid IN ("
-                    "SELECT id FROM search_vector_chunks "
-                    f"WHERE project_id = :project_id AND {stale_entity_filter})"
+                    f"DELETE FROM search_vector_chunks "
+                    f"WHERE project_id = :project_id AND {stale_entity_filter}"
                 ),
                 params,
             )
 
-        # Postgres CASCADE handles embedding deletion automatically
-        await self.repository.execute_query(
-            text(
-                f"DELETE FROM search_vector_chunks "
-                f"WHERE project_id = :project_id AND {stale_entity_filter}"
-            ),
-            params,
-        )
-
         logger.info("Purged stale search rows for deleted entities", project_id=project_id)
 
+    @staticmethod
+    def _entity_embeddings_enabled(entity: Entity) -> bool:
+        """Return whether semantic embeddings should be generated for this entity."""
+        if not entity.entity_metadata:
+            return True
+
+        embed_value = entity.entity_metadata.get("embed")
+        if embed_value is None:
+            return True
+        if isinstance(embed_value, bool):
+            return embed_value
+        if isinstance(embed_value, str):
+            normalized = embed_value.strip().lower()
+            if normalized in {"false", "0", "no", "off"}:
+                return False
+            if normalized in {"true", "1", "yes", "on"}:
+                return True
+        if isinstance(embed_value, (int, float)):
+            return bool(embed_value)
+
+        # Default unknown values to enabled so malformed metadata does not silently
+        # remove notes from semantic search.
+        return True
+
+    async def _clear_entity_vectors(self, entity_id: int) -> None:
+        """Delete derived vector rows for one entity."""
+        from basic_memory.repository.search_repository_base import SearchRepositoryBase
+
+        # Trigger: semantic indexing is disabled for this repository instance.
+        # Why: repositories only create vector tables when semantic search is enabled.
+        # Outcome: skip cleanup because there are no active derived vector rows to maintain.
+        if (
+            isinstance(self.repository, SearchRepositoryBase)
+            and not self.repository._semantic_enabled
+        ):
+            return
+
+        await self.repository.delete_entity_vector_rows(entity_id)
+
     async def index_entity_file(
         self,
         entity: Entity,
@@ -724,7 +878,7 @@ class SearchService:
         await self.repository.delete_by_entity_id(entity_id)
 
     async def handle_delete(self, entity: Entity):
-        """Handle complete entity deletion from search index including observations and relations.
+        """Handle complete entity deletion from search and semantic index state.
 
         This replicates the logic from sync_service.handle_delete() to properly clean up
         all search index entries for an entity and its related data.
@@ -751,3 +905,8 @@ class SearchService:
                 await self.delete_by_permalink(permalink)
             else:
                 await self.delete_by_entity_id(entity.id)
+
+        # Trigger: entity deletion removes the source rows for this note.
+        # Why: semantic chunks/embeddings are stored separately from search_index rows.
+        # Outcome: deleting an entity clears both full-text and vector-derived search state.
+        await self._clear_entity_vectors(entity.id)

src/basic_memory/sync/sync_service.py

@@ -8,7 +8,7 @@ from collections import OrderedDict
 from dataclasses import dataclass, field
 from datetime import datetime
 from pathlib import Path
-from typing import AsyncIterator, Dict, List, Optional, Set, Tuple
+from typing import AsyncIterator, Awaitable, Callable, Dict, List, Optional, Set, Tuple
 
 import aiofiles.os
 
@@ -18,7 +18,15 @@ from sqlalchemy.exc import IntegrityError
 from basic_memory import telemetry
 from basic_memory import db
 from basic_memory.config import BasicMemoryConfig, ConfigManager
-from basic_memory.file_utils import has_frontmatter
+from basic_memory.file_utils import compute_checksum, has_frontmatter
+from basic_memory.indexing import BatchIndexer, IndexFileMetadata, IndexInputFile, IndexProgress
+from basic_memory.indexing.batching import build_index_batches
+from basic_memory.indexing.models import (
+    IndexedEntity,
+    IndexFileWriter,
+    IndexFrontmatterUpdate,
+    IndexFrontmatterWriteResult,
+)
 from basic_memory.ignore_utils import load_bmignore_patterns, should_ignore_path
 from basic_memory.markdown import EntityParser, MarkdownProcessor
 from basic_memory.models import Entity, Project
@@ -31,7 +39,7 @@ from basic_memory.repository import (
 from basic_memory.repository.search_repository import create_search_repository
 from basic_memory.services import EntityService, FileService
 from basic_memory.repository.semantic_errors import SemanticDependenciesMissingError
-from basic_memory.services.exceptions import SyncFatalError
+from basic_memory.services.exceptions import FileOperationError, SyncFatalError
 from basic_memory.services.link_resolver import LinkResolver
 from basic_memory.services.search_service import SearchService
 
@@ -96,6 +104,7 @@ class SyncReport:
     deleted: Set[str] = field(default_factory=set)
     moves: Dict[str, str] = field(default_factory=dict)  # old_path -> new_path
     checksums: Dict[str, str] = field(default_factory=dict)  # path -> checksum
+    scanned_paths: Set[str] = field(default_factory=set)
     skipped_files: List[SkippedFile] = field(default_factory=list)
 
     @property
@@ -118,6 +127,23 @@ class ScanResult:
     errors: Dict[str, str] = field(default_factory=dict)
 
 
+class _FileServiceIndexWriter(IndexFileWriter):
+    """Adapt FileService frontmatter updates to the indexing writer protocol."""
+
+    def __init__(self, file_service: FileService) -> None:
+        self.file_service = file_service
+
+    async def write_frontmatter(
+        self, update: IndexFrontmatterUpdate
+    ) -> IndexFrontmatterWriteResult:
+        # Why: IndexFrontmatterWriteResult lives in indexing/models.py so the indexing
+        # layer does not need to import FileService. This adapter keeps that boundary intact.
+        result = await self.file_service.update_frontmatter_with_result(
+            update.path, update.metadata
+        )
+        return IndexFrontmatterWriteResult(checksum=result.checksum, content=result.content)
+
+
 class SyncService:
     """Syncs documents and knowledge files with database."""
 
@@ -146,6 +172,14 @@ class SyncService:
         # Use OrderedDict for LRU behavior with bounded size to prevent unbounded memory growth
         self._file_failures: OrderedDict[str, FileFailureInfo] = OrderedDict()
         self._max_tracked_failures = 100  # Limit failure cache size
+        self.batch_indexer = BatchIndexer(
+            app_config=app_config,
+            entity_service=entity_service,
+            entity_repository=entity_repository,
+            relation_repository=relation_repository,
+            search_service=search_service,
+            file_writer=_FileServiceIndexWriter(file_service),
+        )
 
     async def _should_skip_file(self, path: str) -> bool:
         """Check if file should be skipped due to repeated failures.
@@ -255,7 +289,12 @@ class SyncService:
             del self._file_failures[path]
 
     async def sync(
-        self, directory: Path, project_name: Optional[str] = None, force_full: bool = False
+        self,
+        directory: Path,
+        project_name: Optional[str] = None,
+        force_full: bool = False,
+        sync_embeddings: bool = True,
+        progress_callback: Callable[[IndexProgress], Awaitable[None]] | None = None,
     ) -> SyncReport:
         """Sync all files with database and update scan watermark.
 
@@ -263,6 +302,8 @@ class SyncService:
             directory: Directory to sync
             project_name: Optional project name
             force_full: If True, force a full scan bypassing watermark optimization
+            sync_embeddings: If True, generate vectors for entities indexed during this sync
+            progress_callback: Optional callback for typed indexing progress updates
         """
 
         start_time = time.time()
@@ -310,55 +351,40 @@ class SyncService:
                 for path in report.deleted:
                     await self.handle_delete(path)
 
-                # then new and modified — collect entity IDs for batch vector embedding
-                synced_entity_ids: list[int] = []
+                # Trigger: the caller requested a full reindex pass through the sync path.
+                # Why: cloud-style "full" semantics should rebuild every current file-backed
+                #      search row, not only the files that differ from the last watermark.
+                # Outcome: progress reflects the whole project and unchanged files are
+                #          re-indexed without inflating the change report itself.
+                changed_paths = (
+                    sorted(report.scanned_paths)
+                    if force_full
+                    else sorted(report.new | report.modified)
+                )
+                indexed_entities, skipped_files = await self._index_changed_files(
+                    changed_paths,
+                    report.checksums,
+                    progress_callback=progress_callback,
+                )
+                report.skipped_files.extend(skipped_files)
+                synced_entity_ids = [indexed.entity_id for indexed in indexed_entities]
 
-                for path in report.new:
-                    entity, _ = await self.sync_file(path, new=True)
-
-                    if entity is not None:
-                        synced_entity_ids.append(entity.id)
-                    # Track if file was skipped
-                    elif await self._should_skip_file(path):
-                        failure_info = self._file_failures[path]
-                        report.skipped_files.append(
-                            SkippedFile(
-                                path=path,
-                                reason=failure_info.last_error,
-                                failure_count=failure_info.count,
-                                first_failed=failure_info.first_failure,
-                            )
-                        )
-
-                for path in report.modified:
-                    entity, _ = await self.sync_file(path, new=False)
-
-                    if entity is not None:
-                        synced_entity_ids.append(entity.id)
-                    # Track if file was skipped
-                    elif await self._should_skip_file(path):
-                        failure_info = self._file_failures[path]
-                        report.skipped_files.append(
-                            SkippedFile(
-                                path=path,
-                                reason=failure_info.last_error,
-                                failure_count=failure_info.count,
-                                first_failed=failure_info.first_failure,
-                            )
-                        )
-
-            # Only resolve relations if there were actual changes
-            # If no files changed, no new unresolved relations could have been created
-            if report.total > 0:
+            # Trigger: either the filesystem diff found changes, or the caller forced a
+            # full reindex and we just reprocessed the current files.
+            # Why: relation resolution should follow the file-processing work that just ran,
+            #      not only the lightweight diff summary.
+            # Outcome: full reindex can heal relation state even when the diff report is empty.
+            if report.total > 0 or (force_full and indexed_entities):
                 with telemetry.scope(
                     "sync.project.resolve_relations", relation_scope="all_pending"
                 ):
-                    await self.resolve_relations()
+                    synced_entity_ids.extend(await self.resolve_relations())
             else:
                 logger.info("Skipping relation resolution - no file changes detected")
 
             # Batch-generate vector embeddings for all synced entities
-            if synced_entity_ids and self.app_config.semantic_search_enabled:
+            synced_entity_ids = list(dict.fromkeys(synced_entity_ids))
+            if synced_entity_ids and sync_embeddings and self.app_config.semantic_search_enabled:
                 try:
                     with telemetry.scope(
                         "sync.project.sync_embeddings",
@@ -425,6 +451,277 @@ class SyncService:
 
             return report
 
+    async def _index_changed_files(
+        self,
+        changed_paths: list[str],
+        checksums_by_path: dict[str, str],
+        *,
+        progress_callback: Callable[[IndexProgress], Awaitable[None]] | None = None,
+    ) -> tuple[list[IndexedEntity], list[SkippedFile]]:
+        """Load, batch, and index changed files without processing them serially."""
+        if not changed_paths:
+            if progress_callback is not None:
+                await progress_callback(
+                    IndexProgress(
+                        files_total=0,
+                        files_processed=0,
+                        batches_total=0,
+                        batches_completed=0,
+                    )
+                )
+            return [], []
+
+        started_at = time.monotonic()
+        files_total = len(changed_paths)
+        files_processed = 0
+        batches_completed = 0
+        skipped_files: list[SkippedFile] = []
+        skipped_paths: set[str] = set()
+        candidate_paths: list[str] = []
+
+        # Trigger: a file exceeded the retry threshold in a previous sync.
+        # Why: repeated retries on unchanged broken files waste the entire batch budget.
+        # Outcome: skip it up front and still count it in progress.
+        for path in changed_paths:
+            if await self._should_skip_file(path):
+                self._append_skipped_file(path, skipped_files, skipped_paths)
+                files_processed += 1
+            else:
+                candidate_paths.append(path)
+
+        (
+            metadata_by_path,
+            metadata_errors,
+            missing_metadata_paths,
+        ) = await self._load_index_file_metadata(
+            candidate_paths,
+            checksums_by_path,
+        )
+        files_processed += len(missing_metadata_paths)
+        files_processed += len(metadata_errors)
+        for path, error in metadata_errors:
+            await self._record_index_failure(path, error, skipped_files, skipped_paths)
+
+        batch_paths = sorted(metadata_by_path)
+        batches = build_index_batches(
+            batch_paths,
+            metadata_by_path,
+            max_files=self.app_config.index_batch_size,
+            max_bytes=self.app_config.index_batch_max_bytes,
+        )
+
+        await self._emit_index_progress(
+            progress_callback,
+            files_total=files_total,
+            files_processed=files_processed,
+            batches_total=len(batches),
+            batches_completed=0,
+            current_batch_bytes=0,
+            started_at=started_at,
+        )
+
+        indexed_entities: list[IndexedEntity] = []
+        shared_permalink_by_path: dict[str, str | None] | None = None
+        if any(
+            metadata.content_type == "text/markdown"
+            or (
+                metadata.content_type is None
+                and Path(metadata.path).suffix.lower() in {".md", ".markdown"}
+            )
+            for metadata in metadata_by_path.values()
+        ):
+            shared_permalink_by_path = {
+                path: permalink
+                for path, permalink in (
+                    await self.entity_repository.get_file_path_to_permalink_map()
+                ).items()
+            }
+
+        for batch in batches:
+            loaded_files, load_errors = await self._load_index_batch_files(
+                batch.paths, metadata_by_path
+            )
+            for path, error in load_errors:
+                await self._record_index_failure(path, error, skipped_files, skipped_paths)
+
+            if loaded_files:
+                batch_result = await self.batch_indexer.index_files(
+                    loaded_files,
+                    max_concurrent=self.app_config.index_entity_max_concurrent,
+                    parse_max_concurrent=self.app_config.index_parse_max_concurrent,
+                    existing_permalink_by_path=shared_permalink_by_path,
+                )
+                indexed_entities.extend(batch_result.indexed)
+
+                indexed_paths = {indexed.path for indexed in batch_result.indexed}
+                for path in indexed_paths:
+                    self._clear_failure(path)
+
+                for path, error in batch_result.errors:
+                    await self._record_index_failure(path, error, skipped_files, skipped_paths)
+
+            files_processed += len(batch.paths)
+            batches_completed += 1
+            await self._emit_index_progress(
+                progress_callback,
+                files_total=files_total,
+                files_processed=files_processed,
+                batches_total=len(batches),
+                batches_completed=batches_completed,
+                current_batch_bytes=batch.total_bytes,
+                started_at=started_at,
+            )
+
+        return indexed_entities, skipped_files
+
+    async def _load_index_file_metadata(
+        self,
+        paths: list[str],
+        checksums_by_path: dict[str, str],
+    ) -> tuple[dict[str, IndexFileMetadata], list[tuple[str, str]], list[str]]:
+        """Load typed metadata for batch planning before any file content is read."""
+        if not paths:
+            return {}, [], []
+
+        semaphore = asyncio.Semaphore(self.app_config.sync_max_concurrent_files)
+        metadata_by_path: dict[str, IndexFileMetadata] = {}
+        errors: dict[str, str] = {}
+        missing_paths: list[str] = []
+
+        async def load(path: str) -> None:
+            async with semaphore:
+                try:
+                    file_metadata = await self.file_service.get_file_metadata(path)
+                    metadata_by_path[path] = IndexFileMetadata(
+                        path=path,
+                        size=file_metadata.size,
+                        checksum=checksums_by_path.get(path),
+                        content_type=self.file_service.content_type(path),
+                        last_modified=file_metadata.modified_at,
+                        created_at=file_metadata.created_at,
+                    )
+                except FileNotFoundError:
+                    await self.handle_delete(path)
+                    missing_paths.append(path)
+                except Exception as exc:
+                    errors[path] = str(exc)
+
+        await asyncio.gather(*(load(path) for path in paths))
+        return (
+            metadata_by_path,
+            [(path, errors[path]) for path in sorted(errors)],
+            sorted(missing_paths),
+        )
+
+    async def _load_index_batch_files(
+        self,
+        paths: list[str],
+        metadata_by_path: dict[str, IndexFileMetadata],
+    ) -> tuple[dict[str, IndexInputFile], list[tuple[str, str]]]:
+        """Read one batch of file contents into typed input objects."""
+        if not paths:
+            return {}, []
+
+        semaphore = asyncio.Semaphore(self.app_config.sync_max_concurrent_files)
+        files: dict[str, IndexInputFile] = {}
+        errors: dict[str, str] = {}
+
+        async def load(path: str) -> None:
+            async with semaphore:
+                metadata = metadata_by_path[path]
+                try:
+                    content = await self.file_service.read_file_bytes(path)
+                    loaded_checksum = await compute_checksum(content)
+                    files[path] = IndexInputFile(
+                        path=metadata.path,
+                        size=metadata.size,
+                        checksum=loaded_checksum,
+                        content_type=metadata.content_type,
+                        last_modified=metadata.last_modified,
+                        created_at=metadata.created_at,
+                        content=content,
+                    )
+                except FileOperationError as exc:
+                    # Trigger: FileService wraps binary read failures in FileOperationError.
+                    # Why: the service contract should stay consistent for direct callers.
+                    # Outcome: sync still treats wrapped missing-file reads as deletions.
+                    if isinstance(exc.__cause__, FileNotFoundError):
+                        await self.handle_delete(path)
+                    else:
+                        errors[path] = str(exc)
+                except Exception as exc:
+                    errors[path] = str(exc)
+
+        await asyncio.gather(*(load(path) for path in paths))
+        return files, [(path, errors[path]) for path in sorted(errors)]
+
+    async def _record_index_failure(
+        self,
+        path: str,
+        error: str,
+        skipped_files: list[SkippedFile],
+        skipped_paths: set[str],
+    ) -> None:
+        """Record a per-file batch failure and promote it to skipped when threshold is reached."""
+        await self._record_failure(path, error)
+        if await self._should_skip_file(path):
+            self._append_skipped_file(path, skipped_files, skipped_paths)
+
+    def _append_skipped_file(
+        self,
+        path: str,
+        skipped_files: list[SkippedFile],
+        skipped_paths: set[str],
+    ) -> None:
+        """Append one skipped file record once per sync run."""
+        if path in skipped_paths or path not in self._file_failures:
+            return
+
+        failure_info = self._file_failures[path]
+        skipped_files.append(
+            SkippedFile(
+                path=path,
+                reason=failure_info.last_error,
+                failure_count=failure_info.count,
+                first_failed=failure_info.first_failure,
+            )
+        )
+        skipped_paths.add(path)
+
+    async def _emit_index_progress(
+        self,
+        progress_callback: Callable[[IndexProgress], Awaitable[None]] | None,
+        *,
+        files_total: int,
+        files_processed: int,
+        batches_total: int,
+        batches_completed: int,
+        current_batch_bytes: int,
+        started_at: float,
+    ) -> None:
+        """Emit a typed indexing progress update when the caller requested one."""
+        if progress_callback is None:
+            return
+
+        elapsed_seconds = max(time.monotonic() - started_at, 0.001)
+        files_per_minute = files_processed / elapsed_seconds * 60 if files_processed else 0.0
+        eta_seconds = None
+        if files_processed and files_total > files_processed:
+            files_per_second = files_processed / elapsed_seconds
+            eta_seconds = (files_total - files_processed) / files_per_second
+
+        await progress_callback(
+            IndexProgress(
+                files_total=files_total,
+                files_processed=files_processed,
+                batches_total=batches_total,
+                batches_completed=batches_completed,
+                current_batch_bytes=current_batch_bytes,
+                files_per_minute=files_per_minute,
+                eta_seconds=eta_seconds,
+            )
+        )
+
     async def scan(self, directory, force_full: bool = False):
         """Smart scan using watermark and file count for large project optimization.
 
@@ -624,6 +921,7 @@ class SyncService:
 
             # Store checksums for files that need syncing
             report.checksums = changed_checksums
+            report.scanned_paths = scanned_paths
 
             scan_duration_ms = int((time.time() - scan_start_time) * 1000)
 
@@ -1081,13 +1379,17 @@ class SyncService:
             # update search index
             await self.search_service.index_entity(updated)
 
-    async def resolve_relations(self, entity_id: int | None = None):
+    async def resolve_relations(self, entity_id: int | None = None) -> set[int]:
         """Try to resolve unresolved relations.
 
         Args:
             entity_id: If provided, only resolve relations for this specific entity.
                       Otherwise, resolve all unresolved relations in the database.
+
+        Returns:
+            Set of source entity IDs whose outgoing relations changed.
         """
+        affected_entity_ids: set[int] = set()
 
         if entity_id:
             # Only get unresolved relations for the specific entity
@@ -1131,8 +1433,7 @@ class SyncService:
                             "to_name": resolved_entity.title,
                         },
                     )
-                    # update search index only on successful resolution
-                    await self.search_service.index_entity(resolved_entity)
+                    affected_entity_ids.add(relation.from_id)
                 except IntegrityError:
                     with telemetry.scope(
                         "sync.relation.resolve_conflict",
@@ -1164,6 +1465,14 @@ class SyncService:
                                 logger.debug(
                                     f"Could not delete duplicate relation {relation.id}: {e}"
                                 )
+                    affected_entity_ids.add(relation.from_id)
+
+        for affected_entity_id in sorted(affected_entity_ids):
+            source_entity = await self.entity_repository.find_by_id(affected_entity_id)
+            if source_entity is not None:
+                await self.search_service.index_entity(source_entity)
+
+        return affected_entity_ids
 
     async def _quick_count_files(self, directory: Path) -> int:
         """Fast file count using find command.

src/basic_memory/sync/watch_service.py

@@ -149,7 +149,7 @@ class WatchService:
 
             # create coroutines to handle changes
             change_handlers = [
-                self.handle_changes(project, changes)  # pyright: ignore
+                self.handle_changes(project, set(changes))
                 for project, changes in project_changes.items()
             ]
 
@@ -502,19 +502,19 @@ class WatchService:
 
         # Add a concise summary instead of a divider
         if processed:
-            changes = []  # pyright: ignore
+            change_summary: list[str] = []
             if add_count > 0:
-                changes.append(f"[green]{add_count} added[/green]")  # pyright: ignore
+                change_summary.append(f"[green]{add_count} added[/green]")
             if modify_count > 0:
-                changes.append(f"[yellow]{modify_count} modified[/yellow]")  # pyright: ignore
+                change_summary.append(f"[yellow]{modify_count} modified[/yellow]")
             if moved_count > 0:
-                changes.append(f"[blue]{moved_count} moved[/blue]")  # pyright: ignore
+                change_summary.append(f"[blue]{moved_count} moved[/blue]")
             if delete_count > 0:
-                changes.append(f"[red]{delete_count} deleted[/red]")  # pyright: ignore
+                change_summary.append(f"[red]{delete_count} deleted[/red]")
 
-            if changes:
-                self.console.print(f"{', '.join(changes)}", style="dim")  # pyright: ignore
-                logger.info(f"changes: {len(changes)}")
+            if change_summary:
+                self.console.print(f"{', '.join(change_summary)}", style="dim")
+                logger.info(f"changes: {len(change_summary)}")
 
         duration_ms = int((time.time() - start_time) * 1000)
         self.state.last_scan = datetime.now()

src/basic_memory/telemetry.py

@@ -40,6 +40,7 @@ class TelemetryState:
 
 _STATE = TelemetryState()
 _LOGFIRE_HANDLER: dict[str, Any] | None = None
+_METRICS: dict[tuple[str, str, str, str], Any] = {}
 
 
 def reset_telemetry_state() -> None:
@@ -55,6 +56,7 @@ def reset_telemetry_state() -> None:
     _STATE.send_to_logfire = False
     _STATE.warnings.clear()
     _LOGFIRE_HANDLER = None
+    _METRICS.clear()
 
 
 def _filter_attributes(attrs: dict[str, Any]) -> dict[str, Any]:
@@ -136,6 +138,58 @@ def pop_telemetry_warnings() -> list[str]:
     return warnings
 
 
+def _get_metric(metric_type: str, name: str, *, unit: str, description: str) -> Any | None:
+    """Create or reuse a Logfire metric instrument when telemetry is enabled."""
+    logfire = _load_logfire()
+    if logfire is None or not _STATE.configured:  # pragma: no cover
+        return None  # pragma: no cover
+
+    metric_key = (metric_type, name, unit, description)
+    cached_metric = _METRICS.get(metric_key)
+    if cached_metric is not None:
+        return cached_metric
+
+    if metric_type == "counter":
+        metric = logfire.metric_counter(name, unit=unit, description=description)
+    elif metric_type == "histogram":
+        metric = logfire.metric_histogram(name, unit=unit, description=description)
+    else:  # pragma: no cover
+        raise ValueError(f"Unsupported metric type: {metric_type}")  # pragma: no cover
+
+    _METRICS[metric_key] = metric
+    return metric
+
+
+def add_counter(
+    name: str,
+    amount: int | float,
+    *,
+    unit: str = "1",
+    description: str = "",
+    **attrs: Any,
+) -> None:
+    """Record a counter increment when telemetry is enabled."""
+    metric = _get_metric("counter", name, unit=unit, description=description)
+    if metric is None:
+        return
+    metric.add(amount, attributes=_filter_attributes(attrs))
+
+
+def record_histogram(
+    name: str,
+    amount: int | float,
+    *,
+    unit: str = "",
+    description: str = "",
+    **attrs: Any,
+) -> None:
+    """Record one histogram sample when telemetry is enabled."""
+    metric = _get_metric("histogram", name, unit=unit, description=description)
+    if metric is None:
+        return
+    metric.record(amount, attributes=_filter_attributes(attrs))
+
+
 @contextmanager
 def contextualize(**attrs: Any) -> Iterator[None]:
     """Apply filtered telemetry attributes to Loguru calls in this scope."""
@@ -176,11 +230,13 @@ def started_span(name: str, **attrs: Any) -> Iterator[Any | None]:
 
 
 __all__ = [
+    "add_counter",
     "contextualize",
     "configure_telemetry",
     "get_logfire_handler",
     "operation",
     "pop_telemetry_warnings",
+    "record_histogram",
     "reset_telemetry_state",
     "scope",
     "span",

test-int/mcp/test_output_format_json_integration.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
+from typing import Any
 
 import pytest
 from fastmcp import Client
@@ -11,7 +12,7 @@ from fastmcp import Client
 from basic_memory.mcp.clients.knowledge import KnowledgeClient
 
 
-def _json_content(tool_result) -> dict | list:
+def _json_content(tool_result) -> Any:
     """Parse a FastMCP tool result content block into JSON."""
     assert len(tool_result.content) == 1
     assert tool_result.content[0].type == "text"

test-int/mcp/test_pagination_integration.py

@@ -7,12 +7,13 @@ results are available.
 """
 
 import json
+from typing import Any
 
 import pytest
 from fastmcp import Client
 
 
-def _json_content(tool_result) -> dict | list:
+def _json_content(tool_result) -> Any:
     """Parse a FastMCP tool result content block into JSON."""
     assert len(tool_result.content) == 1
     assert tool_result.content[0].type == "text"

test-int/semantic/conftest.py

@@ -65,6 +65,11 @@ ALL_COMBOS = [
     SearchCombo("postgres-openai", DatabaseBackend.POSTGRES, "openai", 1536),
 ]
 
+# Benchmark queries compare ranking quality across providers rather than enforcing
+# the stricter production retrieval cutoff. OpenAI paraphrase matches cluster near
+# ~0.37 in this corpus, so the default 0.55 filter hides otherwise-correct results.
+BENCHMARK_MIN_SIMILARITY = 0.3
+
 
 # --- Skip guards ---
 
@@ -229,6 +234,7 @@ async def create_search_service(
         default_project="bench-project",
         database_backend=combo.backend,
         semantic_search_enabled=semantic_enabled,
+        semantic_min_similarity=BENCHMARK_MIN_SIMILARITY,
     )
 
     # Create search repository (backend-specific)

test-int/semantic/test_search_diagnostics.py

@@ -9,6 +9,8 @@ These tests isolate specific problems with the search pipeline:
 
 from __future__ import annotations
 
+from typing import Any, cast
+
 import pytest
 
 from basic_memory.config import DatabaseBackend
@@ -335,11 +337,10 @@ async def test_similarity_formula_analysis(sqlite_engine_factory, tmp_path):
 
         from basic_memory import db as bm_db
 
-        async with bm_db.scoped_session(service.repository.session_maker) as session:
-            await service.repository._prepare_vector_session(session)
-            raw_rows = await service.repository._run_vector_query(
-                session, query_embedding, candidate_limit=20
-            )
+        repo = cast(Any, service.repository)
+        async with bm_db.scoped_session(repo.session_maker) as session:
+            await repo._prepare_vector_session(session)
+            raw_rows = await repo._run_vector_query(session, query_embedding, candidate_limit=20)
 
         print(f"\nQuery: '{query_text}'")
         print(f"  {'chunk_key':<40} {'distance':>10} {'sim_old':>12} {'sim_new':>12}")
@@ -347,7 +348,7 @@ async def test_similarity_formula_analysis(sqlite_engine_factory, tmp_path):
             dist = float(row["best_distance"])
             sim_old = 1.0 / (1.0 + max(dist, 0.0))
             # New formula: L2 distance → cosine similarity for normalized embeddings
-            sim_new = service.repository._distance_to_similarity(dist)
+            sim_new = repo._distance_to_similarity(dist)
             print(f"  {row['chunk_key']:<40} {dist:>10.4f} {sim_old:>12.4f} {sim_new:>12.4f}")
 
 
@@ -431,7 +432,7 @@ async def test_chunking_produces_reasonable_chunks(sqlite_engine_factory, tmp_pa
     service = await create_search_service(
         sqlite_engine_factory, DIAG_COMBO, tmp_path, embedding_provider=provider
     )
-    repo = service.repository
+    repo = cast(Any, service.repository)
 
     # Simulate a typical entity with observations
     text_input = (

test-int/semantic/test_semantic_coverage.py

@@ -13,6 +13,8 @@ Uses postgres-fastembed combo (no OpenAI dependency) with the pgvector container
 
 from __future__ import annotations
 
+from typing import Any, cast
+
 import pytest
 
 from basic_memory.config import DatabaseBackend
@@ -194,7 +196,7 @@ async def test_postgres_vector_dimension_detection(postgres_engine_factory, tmp_
         postgres_engine_factory, PG_FASTEMBED, tmp_path, embedding_provider=provider
     )
 
-    repo = search_service.repository
+    repo = cast(Any, search_service.repository)
 
     # First entity triggers _ensure_vector_tables
     entity = await search_service.entity_repository.create(

test-int/semantic/test_semantic_quality.py

@@ -51,7 +51,7 @@ RECALL_AT_5_THRESHOLDS: dict[tuple[str, str, str], float] = {
     ("sqlite-fastembed", "paraphrase", "hybrid"): 0.25,
     ("postgres-fastembed", "lexical", "hybrid"): 0.37,
     ("postgres-fastembed", "paraphrase", "hybrid"): 0.25,
-    # OpenAI hybrid should handle paraphrases better than FastEmbed
+    # OpenAI hybrid should handle paraphrases better than FastEmbed.
     ("postgres-openai", "lexical", "hybrid"): 0.37,
     ("postgres-openai", "paraphrase", "hybrid"): 0.25,
 }

test-int/test_db_wal_mode.py

@@ -8,6 +8,11 @@ import pytest
 from sqlalchemy import text
 
 
+def _first_value(row):
+    assert row is not None
+    return row[0]
+
+
 @pytest.mark.asyncio
 async def test_wal_mode_enabled(engine_factory, db_backend):
     """Test that WAL mode is enabled on filesystem database connections."""
@@ -19,7 +24,7 @@ async def test_wal_mode_enabled(engine_factory, db_backend):
     # Execute a query to verify WAL mode is enabled
     async with engine.connect() as conn:
         result = await conn.execute(text("PRAGMA journal_mode"))
-        journal_mode = result.fetchone()[0]
+        journal_mode = _first_value(result.fetchone())
 
         # WAL mode should be enabled for filesystem databases
         assert journal_mode.upper() == "WAL"
@@ -35,7 +40,7 @@ async def test_busy_timeout_configured(engine_factory, db_backend):
 
     async with engine.connect() as conn:
         result = await conn.execute(text("PRAGMA busy_timeout"))
-        busy_timeout = result.fetchone()[0]
+        busy_timeout = _first_value(result.fetchone())
 
         # Busy timeout should be 10 seconds (10000 milliseconds)
         assert busy_timeout == 10000
@@ -51,7 +56,7 @@ async def test_synchronous_mode_configured(engine_factory, db_backend):
 
     async with engine.connect() as conn:
         result = await conn.execute(text("PRAGMA synchronous"))
-        synchronous = result.fetchone()[0]
+        synchronous = _first_value(result.fetchone())
 
         # Synchronous should be NORMAL (1)
         assert synchronous == 1
@@ -67,7 +72,7 @@ async def test_cache_size_configured(engine_factory, db_backend):
 
     async with engine.connect() as conn:
         result = await conn.execute(text("PRAGMA cache_size"))
-        cache_size = result.fetchone()[0]
+        cache_size = _first_value(result.fetchone())
 
         # Cache size should be -64000 (64MB)
         assert cache_size == -64000
@@ -83,7 +88,7 @@ async def test_temp_store_configured(engine_factory, db_backend):
 
     async with engine.connect() as conn:
         result = await conn.execute(text("PRAGMA temp_store"))
-        temp_store = result.fetchone()[0]
+        temp_store = _first_value(result.fetchone())
 
         # temp_store should be MEMORY (2)
         assert temp_store == 2
@@ -114,7 +119,7 @@ async def test_windows_locking_mode_when_on_windows(tmp_path, monkeypatch, confi
     ):
         async with engine.connect() as conn:
             result = await conn.execute(text("PRAGMA locking_mode"))
-            locking_mode = result.fetchone()[0]
+            locking_mode = _first_value(result.fetchone())
 
             # Locking mode should be NORMAL on Windows
             assert locking_mode.upper() == "NORMAL"

test-int/test_sync_batching_integration.py

@@ -0,0 +1,201 @@
+"""Integration coverage for batched sync indexing."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from textwrap import dedent
+
+import pytest
+
+from basic_memory.markdown import EntityParser, MarkdownProcessor
+from basic_memory.repository import (
+    EntityRepository,
+    ObservationRepository,
+    ProjectRepository,
+    RelationRepository,
+)
+from basic_memory.repository.search_repository import create_search_repository
+from basic_memory.services import FileService
+from basic_memory.services.entity_service import EntityService
+from basic_memory.services.link_resolver import LinkResolver
+from basic_memory.services.search_service import SearchService
+from basic_memory.sync.sync_service import MAX_CONSECUTIVE_FAILURES, SyncService
+
+
+async def _create_file(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+
+
+async def _create_binary_file(path: Path, content: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(content)
+
+
+async def _build_sync_service(
+    project_root: Path,
+    engine_factory,
+    app_config,
+    test_project,
+) -> SyncService:
+    _, session_maker = engine_factory
+
+    entity_repository = EntityRepository(session_maker, project_id=test_project.id)
+    observation_repository = ObservationRepository(session_maker, project_id=test_project.id)
+    relation_repository = RelationRepository(session_maker, project_id=test_project.id)
+    project_repository = ProjectRepository(session_maker)
+    search_repository = create_search_repository(session_maker, project_id=test_project.id)
+
+    entity_parser = EntityParser(project_root)
+    markdown_processor = MarkdownProcessor(entity_parser)
+    file_service = FileService(project_root, markdown_processor)
+    search_service = SearchService(search_repository, entity_repository, file_service)
+    await search_service.init_search_index()
+    link_resolver = LinkResolver(entity_repository, search_service)
+
+    entity_service = EntityService(
+        entity_parser=entity_parser,
+        entity_repository=entity_repository,
+        observation_repository=observation_repository,
+        relation_repository=relation_repository,
+        file_service=file_service,
+        link_resolver=link_resolver,
+        app_config=app_config,
+    )
+
+    return SyncService(
+        app_config=app_config,
+        entity_service=entity_service,
+        entity_parser=entity_parser,
+        entity_repository=entity_repository,
+        relation_repository=relation_repository,
+        project_repository=project_repository,
+        search_service=search_service,
+        file_service=file_service,
+    )
+
+
+@pytest.mark.asyncio
+async def test_sync_batching_handles_large_single_file_batches_and_resolves_forward_refs(
+    engine_factory,
+    app_config,
+    test_project,
+):
+    app_config.index_batch_size = 2
+    app_config.index_batch_max_bytes = 256
+
+    project_root = Path(test_project.path)
+    sync_service = await _build_sync_service(project_root, engine_factory, app_config, test_project)
+
+    await _create_file(
+        project_root / "notes/alpha.md",
+        dedent(
+            """
+            ---
+            title: Alpha
+            type: note
+            ---
+            # Alpha
+
+            - depends_on [[Target]]
+            """
+        ).strip(),
+    )
+    await _create_file(
+        project_root / "notes/large.md",
+        dedent(
+            f"""
+            ---
+            title: Large
+            type: note
+            ---
+            # Large
+
+            {"x" * 2048}
+            """
+        ).strip(),
+    )
+    await _create_file(
+        project_root / "notes/target.md",
+        dedent(
+            """
+            ---
+            title: Target
+            type: note
+            ---
+            # Target
+            """
+        ).strip(),
+    )
+
+    report = await sync_service.sync(
+        project_root,
+        project_name=test_project.name,
+        force_full=True,
+    )
+
+    alpha = await sync_service.entity_repository.get_by_file_path("notes/alpha.md")
+    large = await sync_service.entity_repository.get_by_file_path("notes/large.md")
+    target = await sync_service.entity_repository.get_by_file_path("notes/target.md")
+
+    assert report.total == 3
+    assert alpha is not None
+    assert large is not None
+    assert target is not None
+    assert large.size is not None
+    assert large.size > app_config.index_batch_max_bytes
+    assert len(alpha.outgoing_relations) == 1
+    assert alpha.outgoing_relations[0].to_id == target.id
+
+
+@pytest.mark.asyncio
+async def test_sync_batching_circuit_breaker_skips_unchanged_broken_markdown_after_threshold(
+    engine_factory,
+    app_config,
+    test_project,
+):
+    app_config.index_batch_size = 1
+    app_config.index_batch_max_bytes = 256
+
+    project_root = Path(test_project.path)
+    sync_service = await _build_sync_service(project_root, engine_factory, app_config, test_project)
+
+    await _create_binary_file(project_root / "notes/broken.md", b"\xff\xfe\xfd")
+
+    last_report = None
+    for _ in range(MAX_CONSECUTIVE_FAILURES):
+        last_report = await sync_service.sync(
+            project_root,
+            project_name=test_project.name,
+            force_full=True,
+        )
+
+    assert last_report is not None
+    assert [skipped.path for skipped in last_report.skipped_files] == ["notes/broken.md"]
+    assert sync_service._file_failures["notes/broken.md"].count == MAX_CONSECUTIVE_FAILURES
+
+    await _create_file(
+        project_root / "notes/good.md",
+        dedent(
+            """
+            ---
+            title: Good
+            type: note
+            ---
+            # Good
+            """
+        ).strip(),
+    )
+
+    report = await sync_service.sync(
+        project_root,
+        project_name=test_project.name,
+        force_full=True,
+    )
+
+    good = await sync_service.entity_repository.get_by_file_path("notes/good.md")
+    broken = await sync_service.entity_repository.get_by_file_path("notes/broken.md")
+
+    assert [skipped.path for skipped in report.skipped_files] == ["notes/broken.md"]
+    assert good is not None
+    assert broken is None

tests/api/v2/conftest.py

@@ -1,5 +1,6 @@
 """Fixtures for V2 API tests."""
 
+from collections.abc import Generator
 from typing import Any, AsyncGenerator
 
 import pytest
@@ -30,7 +31,7 @@ async def client(app: FastAPI) -> AsyncGenerator[AsyncClient, None]:
 
 
 @pytest.fixture(autouse=True)
-def task_scheduler_spy(app: FastAPI) -> list[dict[str, Any]]:
+def task_scheduler_spy(app: FastAPI) -> Generator[list[dict[str, Any]], None, None]:
     """Capture scheduled task specs without executing them."""
     scheduled: list[dict[str, Any]] = []
 

tests/api/v2/test_knowledge_router_telemetry.py

@@ -6,6 +6,7 @@ import importlib
 from contextlib import contextmanager
 from datetime import datetime, timezone
 from types import SimpleNamespace
+from typing import Any, cast
 
 import pytest
 from fastapi import BackgroundTasks, Response
@@ -85,7 +86,7 @@ async def test_create_entity_emits_root_and_nested_spans(monkeypatch) -> None:
             raise AssertionError("non-fast create should not re-read file content")
 
     result = await knowledge_router_module.create_entity(
-        project_id="project-123",
+        project_id=123,
         data=Entity(
             title="Telemetry Entity",
             directory="notes",
@@ -94,11 +95,11 @@ async def test_create_entity_emits_root_and_nested_spans(monkeypatch) -> None:
             content="telemetry content",
         ),
         background_tasks=BackgroundTasks(),
-        entity_service=FakeEntityService(),
-        search_service=FakeSearchService(),
+        entity_service=cast(Any, FakeEntityService()),
+        search_service=cast(Any, FakeSearchService()),
         task_scheduler=FakeTaskScheduler(),
-        file_service=FakeFileService(),
-        app_config=SimpleNamespace(semantic_search_enabled=False),
+        file_service=cast(Any, FakeFileService()),
+        app_config=cast(Any, SimpleNamespace(semantic_search_enabled=False)),
         fast=False,
     )
 
@@ -159,13 +160,13 @@ async def test_update_entity_emits_root_and_nested_spans(monkeypatch) -> None:
         ),
         response=response,
         background_tasks=BackgroundTasks(),
-        project_id="project-123",
-        entity_service=FakeEntityService(),
-        search_service=FakeSearchService(),
-        entity_repository=FakeEntityRepository(),
+        project_id=123,
+        entity_service=cast(Any, FakeEntityService()),
+        search_service=cast(Any, FakeSearchService()),
+        entity_repository=cast(Any, FakeEntityRepository()),
         task_scheduler=FakeTaskScheduler(),
-        file_service=FakeFileService(),
-        app_config=SimpleNamespace(semantic_search_enabled=False),
+        file_service=cast(Any, FakeFileService()),
+        app_config=cast(Any, SimpleNamespace(semantic_search_enabled=False)),
         entity_id=entity.external_id,
         fast=False,
     )
@@ -220,13 +221,13 @@ async def test_edit_entity_emits_root_and_nested_spans(monkeypatch) -> None:
     result = await knowledge_router_module.edit_entity_by_id(
         data=EditEntityRequest(operation="append", content="edited telemetry content"),
         background_tasks=BackgroundTasks(),
-        project_id="project-123",
-        entity_service=FakeEntityService(),
-        search_service=FakeSearchService(),
-        entity_repository=FakeEntityRepository(),
+        project_id=123,
+        entity_service=cast(Any, FakeEntityService()),
+        search_service=cast(Any, FakeSearchService()),
+        entity_repository=cast(Any, FakeEntityRepository()),
         task_scheduler=FakeTaskScheduler(),
-        file_service=FakeFileService(),
-        app_config=SimpleNamespace(semantic_search_enabled=False),
+        file_service=cast(Any, FakeFileService()),
+        app_config=cast(Any, SimpleNamespace(semantic_search_enabled=False)),
         entity_id=entity.external_id,
         fast=False,
     )

tests/api/v2/test_memory_hydration.py

@@ -8,10 +8,12 @@ from __future__ import annotations
 
 from datetime import datetime, timezone
 from types import SimpleNamespace
+from typing import Any
 
 import pytest
 
 from basic_memory.api.v2.utils import to_graph_context
+from basic_memory.schemas.memory import EntitySummary, ObservationSummary, RelationSummary
 from basic_memory.schemas.search import SearchItemType
 from basic_memory.services.context_service import (
     ContextMetadata,
@@ -28,9 +30,9 @@ def _make_entity(id: int, title: str, external_id: str) -> SimpleNamespace:
     return SimpleNamespace(id=id, title=title, external_id=external_id)
 
 
-def _make_row(*, type: str, id: int, root_id: int, **kwargs) -> ContextResultRow:
+def _make_row(*, type: str, id: int, root_id: int, **kwargs: Any) -> ContextResultRow:
     now = kwargs.pop("created_at", datetime.now(timezone.utc))
-    defaults = dict(
+    defaults: dict[str, Any] = dict(
         title=f"Item {id}",
         permalink=f"notes/{id}",
         file_path=f"notes/{id}.md",
@@ -159,20 +161,31 @@ async def test_to_graph_context_batches_entity_hydration_for_recent_activity():
     assert set(repo.calls[0]) == {1, 2, 3}
 
     first_result = graph.results[0]
-    assert first_result.primary_result.external_id == "ext-root"
-    assert first_result.observations[0].entity_external_id == "ext-root"
-    assert first_result.observations[0].title == "Root"
+    first_primary = first_result.primary_result
+    assert isinstance(first_primary, EntitySummary)
+    assert first_primary.external_id == "ext-root"
+
+    first_observation = first_result.observations[0]
+    assert isinstance(first_observation, ObservationSummary)
+    assert first_observation.entity_external_id == "ext-root"
+    assert first_observation.title == "Root"
 
     relation = first_result.related_results[0]
+    assert isinstance(relation, RelationSummary)
     assert relation.from_entity == "Root"
     assert relation.from_entity_external_id == "ext-root"
     assert relation.to_entity == "Child"
     assert relation.to_entity_external_id == "ext-child"
 
     second_result = graph.results[1]
-    assert second_result.primary_result.entity_external_id == "ext-child"
-    assert second_result.primary_result.title == "Child"
-    assert second_result.related_results[0].external_id == "ext-peer"
+    second_primary = second_result.primary_result
+    assert isinstance(second_primary, ObservationSummary)
+    assert second_primary.entity_external_id == "ext-child"
+    assert second_primary.title == "Child"
+
+    peer_result = second_result.related_results[0]
+    assert isinstance(peer_result, EntitySummary)
+    assert peer_result.external_id == "ext-peer"
 
 
 @pytest.mark.asyncio

tests/api/v2/test_project_router.py

@@ -11,6 +11,11 @@ from basic_memory.schemas.project_info import ProjectItem, ProjectStatusResponse
 from basic_memory.schemas.v2 import ProjectResolveResponse
 
 
+def _project_item(project: ProjectItem | None) -> ProjectItem:
+    assert project is not None
+    return project
+
+
 @pytest.mark.asyncio
 async def test_list_projects(client: AsyncClient, test_project: Project, v2_projects_url):
     """Test listing projects returns default_project from the database."""
@@ -67,10 +72,12 @@ async def test_update_project_path_by_id(
         assert response.status_code == 200
         status_response = ProjectStatusResponse.model_validate(response.json())
         assert status_response.status == "success"
-        assert status_response.new_project.external_id == test_project.external_id
+        new_project = _project_item(status_response.new_project)
+        old_project = _project_item(status_response.old_project)
+        assert new_project.external_id == test_project.external_id
         # Normalize paths for cross-platform comparison (Windows uses backslashes, API returns forward slashes)
-        assert Path(status_response.new_project.path) == Path(new_path)
-        assert status_response.old_project.external_id == test_project.external_id
+        assert Path(new_project.path) == Path(new_path)
+        assert old_project.external_id == test_project.external_id
 
 
 @pytest.mark.asyncio
@@ -122,10 +129,12 @@ async def test_set_default_project_by_id(
     status_response = ProjectStatusResponse.model_validate(response.json())
     assert status_response.status == "success"
     assert status_response.default is True
-    assert status_response.new_project.external_id == created_project.external_id
-    assert status_response.new_project.is_default is True
-    assert status_response.old_project.external_id == test_project.external_id
-    assert status_response.old_project.is_default is False
+    new_project = _project_item(status_response.new_project)
+    old_project = _project_item(status_response.old_project)
+    assert new_project.external_id == created_project.external_id
+    assert new_project.is_default is True
+    assert old_project.external_id == test_project.external_id
+    assert old_project.is_default is False
 
 
 @pytest.mark.asyncio
@@ -155,7 +164,8 @@ async def test_delete_project_by_id(
     assert response.status_code == 200
     status_response = ProjectStatusResponse.model_validate(response.json())
     assert status_response.status == "success"
-    assert status_response.old_project.external_id == created_project.external_id
+    old_project = _project_item(status_response.old_project)
+    assert old_project.external_id == created_project.external_id
     assert status_response.new_project is None
 
     # Verify it's deleted - trying to get it should return 404

tests/api/v2/test_search_hydration.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 from datetime import datetime, timezone
 from types import SimpleNamespace
+from typing import Any
 
 import pytest
 
@@ -22,9 +23,9 @@ def _make_entity(id: int, permalink: str) -> SimpleNamespace:
     return SimpleNamespace(id=id, permalink=permalink)
 
 
-def _make_row(*, type: str, id: int, **kwargs) -> SearchIndexRow:
+def _make_row(*, type: str, id: int, **kwargs: Any) -> SearchIndexRow:
     now = datetime.now(timezone.utc)
-    defaults = dict(
+    defaults: dict[str, Any] = dict(
         project_id=1,
         file_path=f"notes/{id}.md",
         created_at=now,

tests/api/v2/test_search_router_telemetry.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import importlib
 from contextlib import contextmanager
+from typing import Any, cast
 
 import pytest
 
@@ -14,6 +15,7 @@ search_router_module = importlib.import_module("basic_memory.api.v2.routers.sear
 
 @pytest.mark.asyncio
 async def test_search_router_wraps_request_in_manual_operation() -> None:
+    router = cast(Any, search_router_module)
     operations: list[tuple[str, dict]] = []
 
     class FakeSearchService:
@@ -28,22 +30,22 @@ async def test_search_router_wraps_request_in_manual_operation() -> None:
     async def fake_to_search_results(entity_service, results):
         return []
 
-    original_operation = search_router_module.telemetry.operation
-    original_to_search_results = search_router_module.to_search_results
-    search_router_module.telemetry.operation = fake_operation
-    search_router_module.to_search_results = fake_to_search_results
+    original_operation = router.telemetry.operation
+    original_to_search_results = router.to_search_results
+    router.telemetry.operation = fake_operation
+    router.to_search_results = fake_to_search_results
     try:
-        response = await search_router_module.search(
+        response = await router.search(
             SearchQuery(text="hello world"),
             FakeSearchService(),
             object(),
-            project_id="project-123",
+            project_id=123,
             page=2,
             page_size=5,
         )
     finally:
-        search_router_module.telemetry.operation = original_operation
-        search_router_module.to_search_results = original_to_search_results
+        router.telemetry.operation = original_operation
+        router.to_search_results = original_to_search_results
 
     assert response.current_page == 2
     assert operations == [

tests/cli/cloud/test_cloud_api_client_and_utils.py

@@ -163,6 +163,7 @@ async def test_cloud_utils_fetch_and_exists_and_create_project(
     created = await create_cloud_project("My Project", api_request=api_request)
     assert created.new_project is not None
     assert created.new_project["name"] == "My Project"
+    assert seen["create_payload"] is not None
     # Path should be permalink-like (kebab)
     assert seen["create_payload"]["path"] == "my-project"
     assert seen["create_payload"]["visibility"] == "workspace"

tests/cli/cloud/test_project_sync_command.py

@@ -1,7 +1,6 @@
 """Tests for cloud sync and bisync command behavior."""
 
 import importlib
-from contextlib import asynccontextmanager
 from types import SimpleNamespace
 
 import pytest
@@ -20,11 +19,10 @@ runner = CliRunner()
         ["cloud", "bisync", "--name", "research"],
     ],
 )
-def test_cloud_sync_commands_use_incremental_db_sync(monkeypatch, argv, config_manager):
-    """Cloud sync commands should not force a full database re-index after file sync."""
+def test_cloud_sync_commands_skip_explicit_cloud_project_sync(monkeypatch, argv, config_manager):
+    """Cloud sync commands should not trigger an extra explicit cloud project sync."""
     project_sync_command = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
 
-    seen: dict[str, object] = {}
     config = config_manager.load_config()
     config.set_project_mode("research", ProjectMode.CLOUD)
     config_manager.save_config(config)
@@ -50,30 +48,10 @@ def test_cloud_sync_commands_use_incremental_db_sync(monkeypatch, argv, config_m
     monkeypatch.setattr(project_sync_command, "project_sync", lambda *args, **kwargs: True)
     monkeypatch.setattr(project_sync_command, "project_bisync", lambda *args, **kwargs: True)
 
-    @asynccontextmanager
-    async def fake_get_client(*, project_name=None, workspace=None):
-        seen["project_name"] = project_name
-        seen["workspace"] = workspace
-        yield object()
-
-    class FakeProjectClient:
-        def __init__(self, _client):
-            pass
-
-        async def sync(self, external_id: str, force_full: bool = False):
-            seen["external_id"] = external_id
-            seen["force_full"] = force_full
-            return {"message": "queued"}
-
-    monkeypatch.setattr(project_sync_command, "get_client", fake_get_client)
-    monkeypatch.setattr(project_sync_command, "ProjectClient", FakeProjectClient)
-
     result = runner.invoke(app, argv)
 
     assert result.exit_code == 0, result.output
-    assert seen["project_name"] == "research"
-    assert seen["external_id"] == "external-project-id"
-    assert seen["force_full"] is False
+    assert "Database sync initiated" not in result.output
 
 
 def test_cloud_bisync_fails_fast_when_sync_entry_disappears(monkeypatch, config_manager):

tests/cli/cloud/test_upload_command_routing.py

@@ -12,7 +12,7 @@ from basic_memory.config import ProjectMode
 runner = CliRunner()
 
 
-def test_cloud_upload_uses_control_plane_client(monkeypatch, tmp_path):
+def test_cloud_upload_uses_control_plane_client(monkeypatch, tmp_path, config_manager):
     """Upload command should use control-plane cloud client for WebDAV PUT operations."""
     import basic_memory.cli.commands.cloud.upload_command as upload_command
 

tests/cli/test_auto_update.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import subprocess
 from datetime import datetime, timedelta, timezone
 from io import StringIO
+from typing import Any, cast
 
 from rich.console import Console
 
@@ -36,6 +37,10 @@ class StubConfigManager:
         self.save_calls += 1
 
 
+def _config_manager(manager: StubConfigManager) -> Any:
+    return cast(Any, manager)
+
+
 def _capture_console() -> tuple[Console, StringIO]:
     """Create a Console that writes to an in-memory buffer."""
     buf = StringIO()
@@ -91,7 +96,7 @@ def test_interval_gate_skips_check_when_recent(tmp_path):
     config.update_check_interval = 3600
     manager = StubConfigManager(config)
 
-    result = run_auto_update(config_manager=manager)
+    result = run_auto_update(config_manager=_config_manager(manager))
 
     assert result.status == AutoUpdateStatus.SKIPPED
     assert result.checked is False
@@ -103,7 +108,7 @@ def test_auto_update_disabled_skips_periodic(tmp_path):
     config.auto_update = False
     manager = StubConfigManager(config)
 
-    result = run_auto_update(config_manager=manager)
+    result = run_auto_update(config_manager=_config_manager(manager))
 
     assert result.status == AutoUpdateStatus.SKIPPED
     assert result.checked is False
@@ -121,7 +126,7 @@ def test_force_bypasses_auto_update_disabled(monkeypatch, tmp_path):
 
     result = run_auto_update(
         force=True,
-        config_manager=manager,
+        config_manager=_config_manager(manager),
         executable="/Users/me/.local/share/uv/tools/basic-memory/bin/python",
     )
 
@@ -171,7 +176,7 @@ def test_homebrew_outdated_triggers_upgrade(monkeypatch, tmp_path):
     monkeypatch.setattr("basic_memory.cli.auto_update._run_subprocess", _fake_run_subprocess)
 
     result = run_auto_update(
-        config_manager=manager,
+        config_manager=_config_manager(manager),
         executable="/opt/homebrew/Cellar/basic-memory/0.18.0/bin/python",
     )
 
@@ -196,7 +201,7 @@ def test_uv_tool_pypi_check_triggers_upgrade(monkeypatch, tmp_path):
     monkeypatch.setattr("basic_memory.cli.auto_update._run_subprocess", _fake_run_subprocess)
 
     result = run_auto_update(
-        config_manager=manager,
+        config_manager=_config_manager(manager),
         executable="/Users/me/.local/share/uv/tools/basic-memory/bin/python",
     )
 
@@ -215,7 +220,7 @@ def test_unknown_manager_returns_manual_update_guidance(monkeypatch, tmp_path):
 
     result = run_auto_update(
         force=True,
-        config_manager=manager,
+        config_manager=_config_manager(manager),
         executable="/usr/local/bin/python3",
     )
 
@@ -229,7 +234,7 @@ def test_uvx_runtime_is_skipped(monkeypatch, tmp_path):
     manager = StubConfigManager(config)
 
     result = run_auto_update(
-        config_manager=manager,
+        config_manager=_config_manager(manager),
         executable="/Users/me/.cache/uv/archive-v0/abc123/bin/python",
     )
 
@@ -256,7 +261,7 @@ def test_mcp_silent_mode_suppresses_subprocess_output(monkeypatch, tmp_path):
     monkeypatch.setattr("basic_memory.cli.auto_update._run_subprocess", _fake_run_subprocess)
 
     result = run_auto_update(
-        config_manager=manager,
+        config_manager=_config_manager(manager),
         executable="/Users/me/.local/share/uv/tools/basic-memory/bin/python",
         silent=True,
     )
@@ -281,7 +286,7 @@ def test_subprocess_oserror_is_non_fatal(monkeypatch, tmp_path):
     monkeypatch.setattr("basic_memory.cli.auto_update._run_subprocess", _raise_oserror)
 
     result = run_auto_update(
-        config_manager=manager,
+        config_manager=_config_manager(manager),
         executable="/Users/me/.local/share/uv/tools/basic-memory/bin/python",
     )
 
@@ -300,7 +305,7 @@ def test_mixed_timezone_timestamp_does_not_crash_interval_gate(monkeypatch, tmp_
     )
 
     result = run_auto_update(
-        config_manager=manager,
+        config_manager=_config_manager(manager),
         executable="/Users/me/.local/share/uv/tools/basic-memory/bin/python",
     )
 

tests/cli/test_cli_exit.py

@@ -28,7 +28,10 @@ def test_bm_help_exits_cleanly():
         ["uv", "run", "bm", "--help"],
         capture_output=True,
         text=True,
-        timeout=10,
+        # Help builds the full command tree, so use a looser timeout than the
+        # version fast path. This test is guarding against hangs, not enforcing
+        # a tight performance budget under full-suite load.
+        timeout=20,
         cwd=Path(__file__).parent.parent.parent,
     )
     assert result.returncode == 0

tests/cli/test_cli_telemetry.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import Any, cast
+
 from basic_memory.cli import app as cli_app
 
 
@@ -38,7 +40,7 @@ def test_app_callback_registers_command_operation(monkeypatch) -> None:
     monkeypatch.setattr(cli_app.telemetry, "operation", fake_operation)
 
     ctx = FakeContext(invoked_subcommand="status")
-    cli_app.app_callback(ctx, version=None)
+    cli_app.app_callback(cast(Any, ctx), version=None)
 
     assert ctx.resources == [resource]
     assert operations == [

tests/cli/test_cloud_authentication.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from contextlib import asynccontextmanager
+from typing import Any, cast
 
 import httpx
 import pytest
@@ -28,6 +29,10 @@ class _StubAuth:
         return self._login_ok
 
 
+def _auth(auth: _StubAuth) -> Any:
+    return cast(Any, auth)
+
+
 def _make_http_client_factory(handler):
     @asynccontextmanager
     async def _factory():
@@ -61,7 +66,7 @@ class TestAPIClientErrorHandling:
             await make_api_request(
                 "GET",
                 "https://test.com/api/endpoint",
-                auth=auth,
+                auth=_auth(auth),
                 http_client_factory=_make_http_client_factory(handler),
             )
 
@@ -88,7 +93,7 @@ class TestAPIClientErrorHandling:
             await make_api_request(
                 "GET",
                 "https://test.com/api/endpoint",
-                auth=auth,
+                auth=_auth(auth),
                 http_client_factory=_make_http_client_factory(handler),
             )
 
@@ -110,7 +115,7 @@ class TestAPIClientErrorHandling:
             await make_api_request(
                 "GET",
                 "https://test.com/api/endpoint",
-                auth=auth,
+                auth=_auth(auth),
                 http_client_factory=_make_http_client_factory(handler),
             )
 

tests/cli/test_cloud_promo.py

@@ -263,7 +263,10 @@ def test_cloud_promo_command_off_sets_opt_out(monkeypatch):
     assert result.exit_code == 0
     assert "Cloud promo messages disabled" in result.stdout
     assert len(instances) == 1
-    assert instances[0].saved_config.cloud_promo_opt_out is True
+    manager = instances[0]
+    assert isinstance(manager, _StubConfigManager)
+    assert manager.saved_config is not None
+    assert manager.saved_config.cloud_promo_opt_out is True
 
 
 def test_cloud_promo_command_on_clears_opt_out(monkeypatch):
@@ -294,7 +297,10 @@ def test_cloud_promo_command_on_clears_opt_out(monkeypatch):
     assert result.exit_code == 0
     assert "Cloud promo messages enabled" in result.stdout
     assert len(instances) == 1
-    assert instances[0].saved_config.cloud_promo_opt_out is False
+    manager = instances[0]
+    assert isinstance(manager, _StubConfigManager)
+    assert manager.saved_config is not None
+    assert manager.saved_config.cloud_promo_opt_out is False
 
 
 # --- _is_interactive_session tests ---

tests/cli/test_db_reindex.py

@@ -0,0 +1,322 @@
+"""Tests for `bm reindex` CLI wiring."""
+
+import asyncio
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from typer.testing import CliRunner
+
+from basic_memory.cli.app import app
+import basic_memory.cli.commands.db as db_cmd  # noqa: F401
+
+
+runner = CliRunner()
+
+
+def _stub_app_config(*, semantic_search_enabled: bool = True) -> SimpleNamespace:
+    """Build the minimal config surface the CLI reindex path expects."""
+    return SimpleNamespace(
+        semantic_search_enabled=semantic_search_enabled,
+        database_path=Path("/tmp/basic-memory.db"),
+        get_project_mode=lambda project_name: None,
+    )
+
+
+def _configure_reindex_cli(monkeypatch, app_config: SimpleNamespace) -> None:
+    """Keep CLI tests focused on reindex wiring instead of full app startup."""
+    monkeypatch.setattr("basic_memory.cli.app.init_cli_logging", lambda: None)
+    monkeypatch.setattr("basic_memory.cli.app.maybe_show_init_line", lambda *_args: None)
+    monkeypatch.setattr("basic_memory.cli.app.maybe_show_cloud_promo", lambda *_args: None)
+    monkeypatch.setattr("basic_memory.cli.app.maybe_run_periodic_auto_update", lambda *_args: None)
+    monkeypatch.setattr(
+        "basic_memory.cli.app.CliContainer.create",
+        lambda: SimpleNamespace(config=app_config, mode=SimpleNamespace(is_cloud=False)),
+    )
+    monkeypatch.setattr(
+        db_cmd,
+        "ConfigManager",
+        lambda: SimpleNamespace(config=app_config),
+    )
+
+
+def test_reindex_defaults_to_incremental_search_and_embeddings(monkeypatch):
+    app_config = _stub_app_config()
+    _configure_reindex_cli(monkeypatch, app_config)
+    captured: dict[str, object] = {}
+
+    async def _stub_reindex(app_config, *, search: bool, embeddings: bool, full: bool, project):
+        captured.update(
+            {
+                "app_config": app_config,
+                "search": search,
+                "embeddings": embeddings,
+                "full": full,
+                "project": project,
+            }
+        )
+
+    monkeypatch.setattr(db_cmd, "_reindex", _stub_reindex)
+    monkeypatch.setattr(db_cmd, "run_with_cleanup", lambda coro: asyncio.run(coro))
+
+    result = runner.invoke(app, ["reindex"])
+
+    assert result.exit_code == 0
+    assert captured == {
+        "app_config": app_config,
+        "search": True,
+        "embeddings": True,
+        "full": False,
+        "project": None,
+    }
+
+
+def test_reindex_full_runs_full_search_and_embeddings(monkeypatch):
+    app_config = _stub_app_config()
+    _configure_reindex_cli(monkeypatch, app_config)
+    captured: dict[str, object] = {}
+
+    async def _stub_reindex(app_config, *, search: bool, embeddings: bool, full: bool, project):
+        captured.update(
+            {
+                "search": search,
+                "embeddings": embeddings,
+                "full": full,
+                "project": project,
+            }
+        )
+
+    monkeypatch.setattr(db_cmd, "_reindex", _stub_reindex)
+    monkeypatch.setattr(db_cmd, "run_with_cleanup", lambda coro: asyncio.run(coro))
+
+    result = runner.invoke(app, ["reindex", "--full"])
+
+    assert result.exit_code == 0
+    assert captured == {
+        "search": True,
+        "embeddings": True,
+        "full": True,
+        "project": None,
+    }
+
+
+def test_reindex_full_search_runs_search_only(monkeypatch):
+    app_config = _stub_app_config()
+    _configure_reindex_cli(monkeypatch, app_config)
+    captured: dict[str, object] = {}
+
+    async def _stub_reindex(app_config, *, search: bool, embeddings: bool, full: bool, project):
+        captured.update(
+            {
+                "search": search,
+                "embeddings": embeddings,
+                "full": full,
+                "project": project,
+            }
+        )
+
+    monkeypatch.setattr(db_cmd, "_reindex", _stub_reindex)
+    monkeypatch.setattr(db_cmd, "run_with_cleanup", lambda coro: asyncio.run(coro))
+
+    result = runner.invoke(app, ["reindex", "--full", "--search"])
+
+    assert result.exit_code == 0
+    assert captured == {
+        "search": True,
+        "embeddings": False,
+        "full": True,
+        "project": None,
+    }
+
+
+def test_reindex_embeddings_only_preserves_incremental_default(monkeypatch):
+    app_config = _stub_app_config()
+    _configure_reindex_cli(monkeypatch, app_config)
+    captured: dict[str, object] = {}
+
+    async def _stub_reindex(app_config, *, search: bool, embeddings: bool, full: bool, project):
+        captured.update(
+            {
+                "search": search,
+                "embeddings": embeddings,
+                "full": full,
+                "project": project,
+            }
+        )
+
+    monkeypatch.setattr(db_cmd, "_reindex", _stub_reindex)
+    monkeypatch.setattr(db_cmd, "run_with_cleanup", lambda coro: asyncio.run(coro))
+
+    result = runner.invoke(app, ["reindex", "--embeddings"])
+
+    assert result.exit_code == 0
+    assert captured == {
+        "search": False,
+        "embeddings": True,
+        "full": False,
+        "project": None,
+    }
+
+
+@pytest.mark.asyncio
+async def test_reindex_project_full_passes_force_full_to_sync_and_reports_mode(monkeypatch):
+    app_config = _stub_app_config()
+    project = SimpleNamespace(id=1, name="foo", path="/tmp/foo")
+    session_maker = object()
+    sync_service = SimpleNamespace(sync=AsyncMock())
+    printed_lines: list[str] = []
+
+    class StubProjectRepository:
+        def __init__(self, _session_maker):
+            self._session_maker = _session_maker
+
+        async def get_active_projects(self):
+            return [project]
+
+    class SilentProgress:
+        def __init__(self, *args, **kwargs):
+            self.tasks: dict[int, SimpleNamespace] = {}
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            return False
+
+        def add_task(self, description, total=1):
+            self.tasks[1] = SimpleNamespace(total=total, description=description)
+            return 1
+
+        def update(self, task_id, **kwargs):
+            if "total" in kwargs:
+                self.tasks[task_id].total = kwargs["total"]
+
+    monkeypatch.setattr(db_cmd, "reconcile_projects_with_config", AsyncMock())
+    monkeypatch.setattr(
+        db_cmd.db,
+        "get_or_create_db",
+        AsyncMock(return_value=(None, session_maker)),
+    )
+    monkeypatch.setattr(db_cmd.db, "shutdown_db", AsyncMock())
+    monkeypatch.setattr(db_cmd, "ProjectRepository", StubProjectRepository)
+    monkeypatch.setattr(db_cmd, "get_sync_service", AsyncMock(return_value=sync_service))
+    monkeypatch.setattr(db_cmd, "Progress", SilentProgress)
+    monkeypatch.setattr(
+        db_cmd.console,
+        "print",
+        lambda message="", *args, **kwargs: printed_lines.append(str(message)),
+    )
+
+    await db_cmd._reindex(
+        app_config,
+        search=True,
+        embeddings=False,
+        full=True,
+        project="foo",
+    )
+
+    sync_service.sync.assert_awaited_once()
+    sync_call = sync_service.sync.await_args
+    assert sync_call.args[0] == Path("/tmp/foo")
+    assert sync_call.kwargs["project_name"] == "foo"
+    assert sync_call.kwargs["force_full"] is True
+    assert sync_call.kwargs["sync_embeddings"] is False
+    assert callable(sync_call.kwargs["progress_callback"])
+    assert any("full scan" in line for line in printed_lines)
+
+
+@pytest.mark.asyncio
+async def test_reindex_embeddings_only_full_passes_force_full_to_vector_reindex(monkeypatch):
+    app_config = _stub_app_config()
+    project = SimpleNamespace(id=1, name="foo", path="/tmp/foo")
+    session_maker = object()
+    printed_lines: list[str] = []
+    vector_reindex_calls: list[dict[str, object]] = []
+
+    class StubProjectRepository:
+        def __init__(self, _session_maker):
+            self._session_maker = _session_maker
+
+        async def get_active_projects(self):
+            return [project]
+
+    class StubSearchService:
+        def __init__(self, search_repository, entity_repository, file_service):
+            self.search_repository = search_repository
+            self.entity_repository = entity_repository
+            self.file_service = file_service
+
+        async def reindex_vectors(self, *, progress_callback=None, force_full: bool = False):
+            vector_reindex_calls.append(
+                {
+                    "progress_callback": progress_callback,
+                    "force_full": force_full,
+                }
+            )
+            return {"total_entities": 2, "embedded": 2, "skipped": 0, "errors": 0}
+
+    class SilentProgress:
+        def __init__(self, *args, **kwargs):
+            self.tasks: dict[int, SimpleNamespace] = {}
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            return False
+
+        def add_task(self, description, total=None):
+            self.tasks[1] = SimpleNamespace(total=total, description=description)
+            return 1
+
+        def update(self, task_id, **kwargs):
+            if "total" in kwargs:
+                self.tasks[task_id].total = kwargs["total"]
+
+    monkeypatch.setattr(db_cmd, "reconcile_projects_with_config", AsyncMock())
+    monkeypatch.setattr(
+        db_cmd.db,
+        "get_or_create_db",
+        AsyncMock(return_value=(None, session_maker)),
+    )
+    monkeypatch.setattr(db_cmd.db, "shutdown_db", AsyncMock())
+    monkeypatch.setattr(db_cmd, "ProjectRepository", StubProjectRepository)
+    monkeypatch.setattr(
+        "basic_memory.repository.search_repository.create_search_repository",
+        lambda *args, **kwargs: object(),
+    )
+    monkeypatch.setattr(
+        "basic_memory.repository.EntityRepository", lambda *args, **kwargs: object()
+    )
+    monkeypatch.setattr(
+        "basic_memory.markdown.entity_parser.EntityParser",
+        lambda *args, **kwargs: object(),
+    )
+    monkeypatch.setattr(
+        "basic_memory.markdown.markdown_processor.MarkdownProcessor",
+        lambda *args, **kwargs: object(),
+    )
+    monkeypatch.setattr(
+        "basic_memory.services.file_service.FileService", lambda *args, **kwargs: object()
+    )
+    monkeypatch.setattr("basic_memory.services.search_service.SearchService", StubSearchService)
+    monkeypatch.setattr(db_cmd, "Progress", SilentProgress)
+    monkeypatch.setattr(
+        db_cmd.console,
+        "print",
+        lambda message="", *args, **kwargs: printed_lines.append(str(message)),
+    )
+
+    await db_cmd._reindex(
+        app_config,
+        search=False,
+        embeddings=True,
+        full=True,
+        project="foo",
+    )
+
+    assert len(vector_reindex_calls) == 1
+    assert vector_reindex_calls[0]["force_full"] is True
+    assert callable(vector_reindex_calls[0]["progress_callback"])
+    assert any("full rebuild" in line for line in printed_lines)

tests/cli/test_json_output.py

@@ -17,7 +17,7 @@ from typer.testing import CliRunner
 from basic_memory.cli.main import app as cli_app
 from basic_memory.mcp.clients.project import ProjectClient
 from basic_memory.schemas.project_info import ProjectList
-from basic_memory.schemas.sync_report import SyncReportResponse
+from basic_memory.schemas.sync_report import SkippedFileResponse, SyncReportResponse
 
 # Importing registers subcommands on the shared app instance.
 import basic_memory.cli.commands.project as project_cmd  # noqa: F401
@@ -76,12 +76,12 @@ SYNC_REPORT_WITH_SKIPPED = SyncReportResponse(
     moves={},
     checksums={},
     skipped_files=[
-        {
-            "path": "bad/file.md",
-            "reason": "parse error",
-            "failure_count": 3,
-            "first_failed": datetime(2025, 6, 15, 12, 0, 0),
-        }
+        SkippedFileResponse(
+            path="bad/file.md",
+            reason="parse error",
+            failure_count=3,
+            first_failed=datetime(2025, 6, 15, 12, 0, 0),
+        )
     ],
     total=0,
 )

tests/cli/test_project_info_cloud_status.py

@@ -0,0 +1,652 @@
+"""Tests for cloud index status in `bm project info`."""
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+import httpx
+import pytest
+import typer
+from typer.testing import CliRunner
+
+from basic_memory.cli.app import app
+from basic_memory.cli.commands.cloud.api_client import CloudAPIError
+from basic_memory.schemas.cloud import CloudProjectIndexStatus, WorkspaceInfo
+from basic_memory.schemas.project_info import (
+    ActivityMetrics,
+    EmbeddingStatus,
+    ProjectInfoResponse,
+    ProjectStatistics,
+    SystemStatus,
+)
+
+# Importing registers project subcommands on the shared app instance.
+import basic_memory.cli.commands.project as project_cmd  # noqa: F401
+
+
+@pytest.fixture
+def runner() -> CliRunner:
+    return CliRunner()
+
+
+@pytest.fixture
+def write_config(tmp_path, monkeypatch):
+    """Write config.json under a temporary HOME and return the file path."""
+    from basic_memory import config as config_module
+
+    def _write(config_data: dict) -> Path:
+        config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
+
+        config_dir = tmp_path / ".basic-memory"
+        config_dir.mkdir(parents=True, exist_ok=True)
+        config_file = config_dir / "config.json"
+        config_file.write_text(json.dumps(config_data, indent=2), encoding="utf-8")
+        monkeypatch.setenv("HOME", str(tmp_path))
+        return config_file
+
+    return _write
+
+
+def _project_info(project_name: str = "demo") -> ProjectInfoResponse:
+    return ProjectInfoResponse(
+        project_name=project_name,
+        project_path=f"/tmp/{project_name}",
+        available_projects={
+            project_name: {
+                "path": f"/tmp/{project_name}",
+                "active": True,
+                "id": 1,
+                "is_default": True,
+                "permalink": project_name,
+            }
+        },
+        default_project=project_name,
+        statistics=ProjectStatistics(
+            total_entities=10,
+            total_observations=20,
+            total_relations=5,
+            total_unresolved_relations=1,
+            note_types={"note": 10},
+            observation_categories={"fact": 20},
+            relation_types={"relates_to": 5},
+            most_connected_entities=[],
+            isolated_entities=2,
+        ),
+        activity=ActivityMetrics(
+            recently_created=[],
+            recently_updated=[],
+            monthly_growth={},
+        ),
+        system=SystemStatus(
+            version="0.0.0-test",
+            database_path="/tmp/memory.db",
+            database_size="1.00 MB",
+            watch_status=None,
+            timestamp=datetime(2026, 4, 9, 12, 0, 0),
+        ),
+        embedding_status=EmbeddingStatus(
+            semantic_search_enabled=True,
+            embedding_provider="fastembed",
+            embedding_model="bge-small-en-v1.5",
+            total_indexed_entities=10,
+            total_entities_with_chunks=10,
+            total_chunks=30,
+            total_embeddings=30,
+            vector_tables_exist=True,
+            reindex_recommended=False,
+            reindex_reason=None,
+        ),
+    )
+
+
+def _cloud_index_status(
+    *,
+    project_name: str = "demo",
+    reindex_recommended: bool = False,
+    reindex_reason: str | None = None,
+) -> CloudProjectIndexStatus:
+    return CloudProjectIndexStatus(
+        project_name=project_name,
+        project_id=1,
+        last_scan_timestamp=1234.5,
+        last_file_count=12,
+        current_file_count=12,
+        total_entities=12,
+        total_note_content_rows=12,
+        note_content_synced=11,
+        note_content_pending=1,
+        note_content_failed=0,
+        note_content_external_changes=0,
+        total_indexed_entities=10,
+        embedding_opt_out_entities=2,
+        embeddable_indexed_entities=8,
+        total_entities_with_chunks=7,
+        total_chunks=21,
+        total_embeddings=21,
+        orphaned_chunks=0,
+        vector_tables_exist=True,
+        materialization_current=False,
+        search_current=False,
+        embeddings_current=False,
+        project_current=not reindex_recommended,
+        reindex_recommended=reindex_recommended,
+        reindex_reason=reindex_reason,
+    )
+
+
+def test_project_info_local_output_is_unchanged(runner: CliRunner, write_config, monkeypatch):
+    """Local project info should not attempt cloud augmentation."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {"demo": {"path": "/tmp/demo", "mode": "local"}},
+            "default_project": "demo",
+        }
+    )
+
+    async def fake_get_project_info(_project_name: str) -> ProjectInfoResponse:
+        return _project_info()
+
+    def fail_if_called(_project_name: str):
+        raise AssertionError("cloud index status should not be fetched for local projects")
+
+    monkeypatch.setattr(project_cmd, "get_project_info", fake_get_project_info)
+    monkeypatch.setattr(project_cmd, "_load_cloud_project_index_status", fail_if_called)
+
+    result = runner.invoke(app, ["project", "info", "demo"], env={"COLUMNS": "240"})
+
+    assert result.exit_code == 0
+    assert "Knowledge Graph" in result.stdout
+    assert "Cloud Index Status" not in result.stdout
+
+
+def test_project_info_cloud_output_includes_index_status(
+    runner: CliRunner, write_config, monkeypatch
+):
+    """Cloud project info should render the extra Cloud Index Status block."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {
+                "demo": {
+                    "path": "/tmp/demo",
+                    "mode": "cloud",
+                    "workspace_id": "11111111-1111-1111-1111-111111111111",
+                }
+            },
+            "default_project": "demo",
+            "cloud_api_key": "bmc_test_key_123",
+        }
+    )
+
+    async def fake_get_project_info(_project_name: str) -> ProjectInfoResponse:
+        return _project_info()
+
+    def fake_load_cloud_project_index_status(_project_name: str):
+        return (
+            _cloud_index_status(
+                reindex_recommended=True,
+                reindex_reason="Search index coverage does not match the current file count",
+            ),
+            None,
+        )
+
+    monkeypatch.setattr(project_cmd, "get_project_info", fake_get_project_info)
+    monkeypatch.setattr(
+        project_cmd, "_load_cloud_project_index_status", fake_load_cloud_project_index_status
+    )
+
+    result = runner.invoke(app, ["project", "info", "demo"], env={"COLUMNS": "240"})
+
+    assert result.exit_code == 0
+    assert "Cloud Index Status" in result.stdout
+    assert "Files" in result.stdout
+    assert "12" in result.stdout
+    assert "Note content" in result.stdout
+    assert "11/12" in result.stdout
+    assert "Search" in result.stdout
+    assert "10/12" in result.stdout
+    assert "Embeddable" in result.stdout
+    assert "8" in result.stdout
+    assert "Vectorized" in result.stdout
+    assert "7/8" in result.stdout
+    assert "Reindex recommended" in result.stdout
+    assert "Search index coverage does not match the current file count" in result.stdout
+
+
+def test_project_info_cloud_output_warns_when_index_lookup_fails(
+    runner: CliRunner, write_config, monkeypatch
+):
+    """Cloud project info should keep rendering when the admin lookup fails."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {
+                "demo": {
+                    "path": "/tmp/demo",
+                    "mode": "cloud",
+                    "workspace_id": "11111111-1111-1111-1111-111111111111",
+                }
+            },
+            "default_project": "demo",
+            "cloud_api_key": "bmc_test_key_123",
+        }
+    )
+
+    async def fake_get_project_info(_project_name: str) -> ProjectInfoResponse:
+        return _project_info()
+
+    def fake_load_cloud_project_index_status(_project_name: str):
+        return None, "HTTP 503: index-status endpoint unavailable"
+
+    monkeypatch.setattr(project_cmd, "get_project_info", fake_get_project_info)
+    monkeypatch.setattr(
+        project_cmd, "_load_cloud_project_index_status", fake_load_cloud_project_index_status
+    )
+
+    result = runner.invoke(app, ["project", "info", "demo"], env={"COLUMNS": "240"})
+
+    assert result.exit_code == 0
+    assert "Knowledge Graph" in result.stdout
+    assert "Cloud Index Status" in result.stdout
+    assert "Warning" in result.stdout
+    assert "HTTP 503: index-status endpoint unavailable" in result.stdout
+
+
+def test_project_info_json_includes_cloud_index_status(
+    runner: CliRunner, write_config, monkeypatch
+):
+    """JSON output should include the matched cloud index status block."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {
+                "demo": {
+                    "path": "/tmp/demo",
+                    "mode": "cloud",
+                    "workspace_id": "11111111-1111-1111-1111-111111111111",
+                }
+            },
+            "default_project": "demo",
+            "cloud_api_key": "bmc_test_key_123",
+        }
+    )
+
+    async def fake_get_project_info(_project_name: str) -> ProjectInfoResponse:
+        return _project_info()
+
+    def fake_load_cloud_project_index_status(_project_name: str):
+        return _cloud_index_status(), None
+
+    monkeypatch.setattr(project_cmd, "get_project_info", fake_get_project_info)
+    monkeypatch.setattr(
+        project_cmd, "_load_cloud_project_index_status", fake_load_cloud_project_index_status
+    )
+
+    result = runner.invoke(app, ["project", "info", "demo", "--json"])
+
+    assert result.exit_code == 0
+    data = json.loads(result.stdout)
+    assert data["project_name"] == "demo"
+    assert data["cloud_index_status"]["project_name"] == "demo"
+    assert data["cloud_index_status"]["current_file_count"] == 12
+    assert data["cloud_index_status"]["note_content_synced"] == 11
+    assert data["cloud_index_status"]["embeddable_indexed_entities"] == 8
+    assert data["cloud_index_status"]["total_entities_with_chunks"] == 7
+    assert data["cloud_index_status_error"] is None
+
+
+def test_project_info_json_includes_cloud_error_when_lookup_fails(
+    runner: CliRunner, write_config, monkeypatch
+):
+    """JSON output should preserve project info when the cloud status lookup fails."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {
+                "demo": {
+                    "path": "/tmp/demo",
+                    "mode": "cloud",
+                    "workspace_id": "11111111-1111-1111-1111-111111111111",
+                }
+            },
+            "default_project": "demo",
+            "cloud_api_key": "bmc_test_key_123",
+        }
+    )
+
+    async def fake_get_project_info(_project_name: str) -> ProjectInfoResponse:
+        return _project_info()
+
+    def fake_load_cloud_project_index_status(_project_name: str):
+        return None, "HTTP 503: index-status endpoint unavailable"
+
+    monkeypatch.setattr(project_cmd, "get_project_info", fake_get_project_info)
+    monkeypatch.setattr(
+        project_cmd, "_load_cloud_project_index_status", fake_load_cloud_project_index_status
+    )
+
+    result = runner.invoke(app, ["project", "info", "demo", "--json"])
+
+    assert result.exit_code == 0
+    data = json.loads(result.stdout)
+    assert data["project_name"] == "demo"
+    assert data["cloud_index_status"] is None
+    assert data["cloud_index_status_error"] == "HTTP 503: index-status endpoint unavailable"
+
+
+def test_uses_cloud_project_info_route_respects_flags_and_project_mode(write_config, monkeypatch):
+    """Route detection should stay local unless flags or cloud mode require augmentation."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {
+                "local-demo": {"path": "/tmp/local-demo", "mode": "local"},
+                "cloud-demo": {"path": "/tmp/cloud-demo", "mode": "cloud"},
+            },
+            "default_project": "local-demo",
+            "cloud_api_key": "bmc_test_key_123",
+        }
+    )
+
+    assert (
+        project_cmd._uses_cloud_project_info_route("cloud-demo", local=False, cloud=False) is True
+    )
+    assert (
+        project_cmd._uses_cloud_project_info_route("local-demo", local=False, cloud=False) is False
+    )
+    assert project_cmd._uses_cloud_project_info_route("local-demo", local=False, cloud=True) is True
+    assert (
+        project_cmd._uses_cloud_project_info_route("cloud-demo", local=True, cloud=False) is False
+    )
+
+
+def test_resolve_cloud_status_workspace_id_prefers_project_workspace(write_config):
+    """Cloud status lookup should use the project workspace before any fallback lookup."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {
+                "demo": {
+                    "path": "/tmp/demo",
+                    "mode": "cloud",
+                    "workspace_id": "project-workspace",
+                }
+            },
+            "default_project": "demo",
+            "cloud_api_key": "bmc_test_key_123",
+            "default_workspace": "default-workspace",
+        }
+    )
+
+    assert project_cmd._resolve_cloud_status_workspace_id("demo") == "project-workspace"
+
+
+def test_resolve_cloud_status_workspace_id_uses_fallback_resolution(write_config, monkeypatch):
+    """Cloud status lookup should fall back to workspace discovery when config has no workspace."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {"demo": {"path": "/tmp/demo", "mode": "cloud"}},
+            "default_project": "demo",
+            "cloud_api_key": "bmc_test_key_123",
+        }
+    )
+
+    monkeypatch.setattr(
+        project_cmd, "_resolve_workspace_id", lambda _config, _workspace: "resolved"
+    )
+
+    assert project_cmd._resolve_cloud_status_workspace_id("demo") == "resolved"
+
+
+def test_resolve_cloud_status_workspace_id_requires_credentials(write_config):
+    """Cloud status lookup should fail fast when no credentials are available."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {"demo": {"path": "/tmp/demo", "mode": "cloud"}},
+            "default_project": "demo",
+        }
+    )
+
+    with pytest.raises(RuntimeError, match="Cloud credentials not found"):
+        project_cmd._resolve_cloud_status_workspace_id("demo")
+
+
+@pytest.mark.asyncio
+async def test_resolve_cloud_status_workspace_id_async_auto_discovers_single_workspace(
+    write_config, monkeypatch
+):
+    """Async cloud status lookup should auto-select a single available workspace."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {"demo": {"path": "/tmp/demo", "mode": "cloud"}},
+            "default_project": "demo",
+            "cloud_api_key": "bmc_test_key_123",
+        }
+    )
+
+    async def fake_get_available_workspaces():
+        return [
+            WorkspaceInfo(
+                tenant_id="11111111-1111-1111-1111-111111111111",
+                workspace_type="personal",
+                name="Personal",
+                role="owner",
+            )
+        ]
+
+    monkeypatch.setattr(
+        "basic_memory.mcp.project_context.get_available_workspaces",
+        fake_get_available_workspaces,
+    )
+
+    workspace_id = await project_cmd._resolve_cloud_status_workspace_id_async("demo")
+
+    assert workspace_id == "11111111-1111-1111-1111-111111111111"
+
+
+def test_match_cloud_index_status_project_prefers_exact_then_permalink():
+    """Project matching should use exact names first, then a unique permalink match."""
+    exact = _cloud_index_status(project_name="Demo Project")
+    permalink_match = _cloud_index_status(project_name="demo-project")
+    unrelated = _cloud_index_status(project_name="other")
+
+    assert (
+        project_cmd._match_cloud_index_status_project("Demo Project", [exact, unrelated]) is exact
+    )
+    assert (
+        project_cmd._match_cloud_index_status_project("Demo Project", [permalink_match, unrelated])
+        is permalink_match
+    )
+    assert (
+        project_cmd._match_cloud_index_status_project(
+            "Demo Project",
+            [permalink_match, _cloud_index_status(project_name="Demo Project!!")],
+        )
+        is None
+    )
+
+
+def test_format_cloud_index_status_error_prefers_cloud_api_detail():
+    """Cloud API errors should surface the most useful available detail."""
+    assert project_cmd._format_cloud_index_status_error(RuntimeError("boom")) == "boom"
+    assert (
+        project_cmd._format_cloud_index_status_error(
+            CloudAPIError("fail", status_code=503, detail={"detail": "down"})
+        )
+        == "HTTP 503: down"
+    )
+    assert (
+        project_cmd._format_cloud_index_status_error(
+            CloudAPIError("fail", status_code=503, detail={"detail": {"message": "nested"}})
+        )
+        == "HTTP 503: nested"
+    )
+    assert (
+        project_cmd._format_cloud_index_status_error(
+            CloudAPIError("fail", status_code=503, detail={"detail": {"detail": "nested-detail"}})
+        )
+        == "HTTP 503: nested-detail"
+    )
+    assert (
+        project_cmd._format_cloud_index_status_error(CloudAPIError("fail", status_code=503))
+        == "HTTP 503"
+    )
+
+
+@pytest.mark.asyncio
+async def test_fetch_cloud_project_index_status_returns_matching_project(write_config, monkeypatch):
+    """Cloud index status fetch should validate the tenant payload and return the matched project."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {"demo": {"path": "/tmp/demo", "mode": "cloud"}},
+            "default_project": "demo",
+            "cloud_api_key": "bmc_test_key_123",
+            "cloud_host": "https://cloud.example.test",
+        }
+    )
+
+    async def fake_resolve_workspace(_project_name: str) -> str:
+        return "11111111-1111-1111-1111-111111111111"
+
+    monkeypatch.setattr(
+        project_cmd, "_resolve_cloud_status_workspace_id_async", fake_resolve_workspace
+    )
+
+    async def fake_make_api_request(**kwargs):
+        assert kwargs["method"] == "GET"
+        assert (
+            kwargs["url"]
+            == "https://cloud.example.test/admin/tenants/11111111-1111-1111-1111-111111111111/index-status"
+        )
+        return httpx.Response(
+            200,
+            json={
+                "tenant_id": "11111111-1111-1111-1111-111111111111",
+                "fly_app_name": "demo-app",
+                "email": "demo@example.com",
+                "projects": [_cloud_index_status().model_dump()],
+                "error": None,
+            },
+        )
+
+    monkeypatch.setattr(project_cmd, "make_api_request", fake_make_api_request)
+
+    status = await project_cmd._fetch_cloud_project_index_status("demo")
+
+    assert status.project_name == "demo"
+    assert status.current_file_count == 12
+
+
+@pytest.mark.asyncio
+async def test_fetch_cloud_project_index_status_handles_exit_and_missing_project(
+    write_config, monkeypatch
+):
+    """Cloud fetch should convert auth exits and fail when the project is missing."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {"demo": {"path": "/tmp/demo", "mode": "cloud"}},
+            "default_project": "demo",
+            "cloud_api_key": "bmc_test_key_123",
+            "cloud_host": "https://cloud.example.test",
+        }
+    )
+
+    async def fake_resolve_workspace(_project_name: str) -> str:
+        return "tenant-1"
+
+    monkeypatch.setattr(
+        project_cmd, "_resolve_cloud_status_workspace_id_async", fake_resolve_workspace
+    )
+
+    async def fake_make_api_request_exit(**_kwargs):
+        raise typer.Exit(1)
+
+    monkeypatch.setattr(project_cmd, "make_api_request", fake_make_api_request_exit)
+
+    with pytest.raises(RuntimeError, match="Cloud credentials not found"):
+        await project_cmd._fetch_cloud_project_index_status("demo")
+
+    async def fake_make_api_request_missing(**_kwargs):
+        return httpx.Response(
+            200,
+            json={
+                "tenant_id": "tenant-1",
+                "fly_app_name": "demo-app",
+                "email": "demo@example.com",
+                "projects": [_cloud_index_status(project_name="other").model_dump()],
+                "error": None,
+            },
+        )
+
+    monkeypatch.setattr(project_cmd, "make_api_request", fake_make_api_request_missing)
+
+    with pytest.raises(RuntimeError, match="was not found in workspace index status"):
+        await project_cmd._fetch_cloud_project_index_status("demo")
+
+
+@pytest.mark.asyncio
+async def test_fetch_cloud_project_index_status_preserves_successful_exit_and_tenant_error(
+    write_config, monkeypatch
+):
+    """Only non-zero typer exits should be converted; tenant-level errors should bubble clearly."""
+    write_config(
+        {
+            "env": "dev",
+            "projects": {"demo": {"path": "/tmp/demo", "mode": "cloud"}},
+            "default_project": "demo",
+            "cloud_api_key": "bmc_test_key_123",
+            "cloud_host": "https://cloud.example.test",
+        }
+    )
+
+    async def fake_resolve_workspace(_project_name: str) -> str:
+        return "tenant-1"
+
+    monkeypatch.setattr(
+        project_cmd, "_resolve_cloud_status_workspace_id_async", fake_resolve_workspace
+    )
+
+    async def fake_make_api_request_success_exit(**_kwargs):
+        raise typer.Exit(0)
+
+    monkeypatch.setattr(project_cmd, "make_api_request", fake_make_api_request_success_exit)
+
+    with pytest.raises(typer.Exit) as exc_info:
+        await project_cmd._fetch_cloud_project_index_status("demo")
+    assert exc_info.value.exit_code == 0
+
+    async def fake_make_api_request_tenant_error(**_kwargs):
+        return httpx.Response(
+            200,
+            json={
+                "tenant_id": "tenant-1",
+                "fly_app_name": "demo-app",
+                "email": "demo@example.com",
+                "projects": [],
+                "error": "tenant is unavailable",
+            },
+        )
+
+    monkeypatch.setattr(project_cmd, "make_api_request", fake_make_api_request_tenant_error)
+
+    with pytest.raises(RuntimeError, match="tenant is unavailable"):
+        await project_cmd._fetch_cloud_project_index_status("demo")
+
+
+def test_build_cloud_index_status_section_handles_missing_status():
+    """The renderer should return a safe header-only table if invariants are broken."""
+    table = project_cmd._build_cloud_index_status_section(None, None)
+    assert table is None
+
+    warning_table = project_cmd._build_cloud_index_status_section(
+        None, "HTTP 503: index-status endpoint unavailable"
+    )
+    assert warning_table is not None

tests/cli/test_project_list_and_ls.py

@@ -139,6 +139,82 @@ def test_project_list_shows_local_cloud_presence_and_routes(
     assert "/beta" in result.stdout
 
 
+def test_project_list_shows_display_name_for_private_projects(
+    runner: CliRunner, write_config, mock_client, tmp_path, monkeypatch
+):
+    """Private projects should show display_name ('My Project') instead of raw UUID name."""
+    private_uuid = "f1df8f39-d5aa-4095-ae05-8c5a2883029a"
+
+    write_config(
+        {
+            "env": "dev",
+            "projects": {},
+            "default_project": "main",
+            "cloud_api_key": "bmc_test_key_123",
+        }
+    )
+
+    local_payload = {
+        "projects": [
+            {
+                "id": 1,
+                "external_id": "11111111-1111-1111-1111-111111111111",
+                "name": "main",
+                "path": "/main",
+                "is_default": True,
+            }
+        ],
+        "default_project": "main",
+    }
+
+    cloud_payload = {
+        "projects": [
+            {
+                "id": 1,
+                "external_id": "11111111-1111-1111-1111-111111111111",
+                "name": "main",
+                "path": "/main",
+                "is_default": True,
+            },
+            {
+                "id": 2,
+                "external_id": "22222222-2222-2222-2222-222222222222",
+                "name": private_uuid,
+                "path": f"/{private_uuid}",
+                "is_default": False,
+                "display_name": "My Project",
+                "is_private": True,
+            },
+        ],
+        "default_project": "main",
+    }
+
+    async def fake_list_projects(self):
+        if os.getenv("BASIC_MEMORY_FORCE_CLOUD", "").lower() in ("true", "1", "yes"):
+            return ProjectList.model_validate(cloud_payload)
+        return ProjectList.model_validate(local_payload)
+
+    monkeypatch.setattr(ProjectClient, "list_projects", fake_list_projects)
+
+    result = runner.invoke(app, ["project", "list"], env={"COLUMNS": "240"})
+
+    assert result.exit_code == 0, f"Exit code: {result.exit_code}, output: {result.stdout}"
+    # Rich table should show display_name in the Name column
+    assert "My Project" in result.stdout
+    lines = result.stdout.splitlines()
+    project_line = next(line for line in lines if "My Project" in line)
+    name_cell = project_line.split("│")[1].strip()
+    assert name_cell == "My Project"
+
+    # JSON output should preserve canonical name for scripting, with display_name as separate field
+    json_result = runner.invoke(app, ["project", "list", "--json"], env={"COLUMNS": "240"})
+    assert json_result.exit_code == 0
+    data = json.loads(json_result.stdout)
+    private_project = next(p for p in data["projects"] if p.get("display_name") == "My Project")
+    assert private_project["name"] == private_uuid
+    assert private_project["display_name"] == "My Project"
+
+
 def test_project_ls_local_mode_defaults_to_local_route(
     runner: CliRunner, write_config, mock_client, tmp_path, monkeypatch
 ):

tests/db/test_issue_254_foreign_key_constraints.py

@@ -137,6 +137,7 @@ async def test_issue_254_reproduction(project_service: ProjectService):
         # Create project and entity
         await project_service.add_project(test_project_name, test_project_path)
         project = await project_service.get_project(test_project_name)
+        assert project is not None
 
         from basic_memory.repository.entity_repository import EntityRepository
 

tests/indexing/test_batch_indexer.py

@@ -0,0 +1,563 @@
+"""Tests for the reusable batch indexing executor."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from textwrap import dedent
+
+import pytest
+from sqlalchemy import text
+
+from basic_memory.indexing import (
+    BatchIndexer,
+    IndexFrontmatterUpdate,
+    IndexFrontmatterWriteResult,
+    IndexInputFile,
+)
+from basic_memory.services.exceptions import SyncFatalError
+
+
+class _TestFileWriter:
+    """Adapt the real FileService for batch indexer tests."""
+
+    def __init__(self, file_service) -> None:
+        self.file_service = file_service
+
+    async def write_frontmatter(
+        self, update: IndexFrontmatterUpdate
+    ) -> IndexFrontmatterWriteResult:
+        result = await self.file_service.update_frontmatter_with_result(
+            update.path, update.metadata
+        )
+        return IndexFrontmatterWriteResult(checksum=result.checksum, content=result.content)
+
+
+async def _create_file(path: Path, content: str | bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if isinstance(content, bytes):
+        path.write_bytes(content)
+    else:
+        path.write_text(content)
+
+
+async def _load_input(file_service, path: str) -> IndexInputFile:
+    metadata = await file_service.get_file_metadata(path)
+    return IndexInputFile(
+        path=path,
+        size=metadata.size,
+        checksum=await file_service.compute_checksum(path),
+        content_type=file_service.content_type(path),
+        last_modified=metadata.modified_at,
+        created_at=metadata.created_at,
+        content=await file_service.read_file_bytes(path),
+    )
+
+
+def _make_batch_indexer(
+    app_config, entity_service, entity_repository, relation_repository, search_service, file_service
+) -> BatchIndexer:
+    return BatchIndexer(
+        app_config=app_config,
+        entity_service=entity_service,
+        entity_repository=entity_repository,
+        relation_repository=relation_repository,
+        search_service=search_service,
+        file_writer=_TestFileWriter(file_service),
+    )
+
+
+@pytest.mark.asyncio
+async def test_batch_indexer_parses_markdown_with_parallel_path(
+    app_config,
+    entity_service,
+    entity_repository,
+    relation_repository,
+    search_service,
+    file_service,
+    project_config,
+):
+    path_one = "notes/one.md"
+    path_two = "notes/two.md"
+    await _create_file(
+        project_config.home / path_one,
+        dedent(
+            """
+            ---
+            title: One
+            type: note
+            ---
+            # One
+            """
+        ).strip(),
+    )
+    await _create_file(
+        project_config.home / path_two,
+        dedent(
+            """
+            ---
+            title: Two
+            type: note
+            ---
+            # Two
+            """
+        ).strip(),
+    )
+
+    files = {
+        path_one: await _load_input(file_service, path_one),
+        path_two: await _load_input(file_service, path_two),
+    }
+    batch_indexer = _make_batch_indexer(
+        app_config,
+        entity_service,
+        entity_repository,
+        relation_repository,
+        search_service,
+        file_service,
+    )
+
+    original_parse = entity_service.entity_parser.parse_markdown_content
+    in_flight = 0
+    max_in_flight = 0
+
+    async def spy_parse(*args, **kwargs):
+        nonlocal in_flight, max_in_flight
+        in_flight += 1
+        max_in_flight = max(max_in_flight, in_flight)
+        await asyncio.sleep(0.05)
+        try:
+            return await original_parse(*args, **kwargs)
+        finally:
+            in_flight -= 1
+
+    entity_service.entity_parser.parse_markdown_content = spy_parse
+    try:
+        result = await batch_indexer.index_files(
+            files,
+            max_concurrent=2,
+            parse_max_concurrent=2,
+        )
+    finally:
+        entity_service.entity_parser.parse_markdown_content = original_parse
+
+    assert max_in_flight >= 2
+    assert len(result.indexed) == 2
+    assert result.errors == []
+
+
+@pytest.mark.asyncio
+async def test_batch_indexer_creates_entities_with_parallel_path(
+    app_config,
+    entity_service,
+    entity_repository,
+    relation_repository,
+    search_service,
+    file_service,
+    project_config,
+):
+    path_one = "notes/alpha.md"
+    path_two = "notes/beta.md"
+    await _create_file(
+        project_config.home / path_one,
+        dedent(
+            """
+            ---
+            title: Alpha
+            type: note
+            ---
+            # Alpha
+            """
+        ).strip(),
+    )
+    await _create_file(
+        project_config.home / path_two,
+        dedent(
+            """
+            ---
+            title: Beta
+            type: note
+            ---
+            # Beta
+            """
+        ).strip(),
+    )
+
+    files = {
+        path_one: await _load_input(file_service, path_one),
+        path_two: await _load_input(file_service, path_two),
+    }
+    batch_indexer = _make_batch_indexer(
+        app_config,
+        entity_service,
+        entity_repository,
+        relation_repository,
+        search_service,
+        file_service,
+    )
+
+    original_upsert = entity_service.upsert_entity_from_markdown
+    in_flight = 0
+    max_in_flight = 0
+
+    async def spy_upsert(*args, **kwargs):
+        nonlocal in_flight, max_in_flight
+        in_flight += 1
+        max_in_flight = max(max_in_flight, in_flight)
+        await asyncio.sleep(0.05)
+        try:
+            return await original_upsert(*args, **kwargs)
+        finally:
+            in_flight -= 1
+
+    entity_service.upsert_entity_from_markdown = spy_upsert
+    try:
+        result = await batch_indexer.index_files(
+            files,
+            max_concurrent=2,
+            parse_max_concurrent=2,
+        )
+    finally:
+        entity_service.upsert_entity_from_markdown = original_upsert
+
+    assert max_in_flight >= 2
+    assert len(result.indexed) == 2
+    assert result.errors == []
+
+
+@pytest.mark.asyncio
+async def test_batch_indexer_returns_original_markdown_content_when_no_frontmatter_rewrite(
+    app_config,
+    entity_service,
+    entity_repository,
+    relation_repository,
+    search_service,
+    file_service,
+    project_config,
+):
+    app_config.disable_permalinks = True
+
+    path = "notes/original.md"
+    original_content = dedent(
+        """
+        ---
+        title: Original
+        type: note
+        ---
+        # Original
+        """
+    ).strip()
+    await _create_file(project_config.home / path, original_content)
+
+    files = {path: await _load_input(file_service, path)}
+    batch_indexer = _make_batch_indexer(
+        app_config,
+        entity_service,
+        entity_repository,
+        relation_repository,
+        search_service,
+        file_service,
+    )
+
+    result = await batch_indexer.index_files(
+        files,
+        max_concurrent=1,
+        parse_max_concurrent=1,
+    )
+
+    # Trigger: Windows persists CRLF for text writes even when the test literal uses LF.
+    # Why: this assertion cares about "no rewrite happened", not about forcing one newline
+    #      convention across platforms.
+    # Outcome: compare against the exact markdown text stored on disk for this file.
+    persisted_content = (project_config.home / path).read_bytes().decode("utf-8")
+
+    assert result.errors == []
+    assert len(result.indexed) == 1
+    assert result.indexed[0].markdown_content == persisted_content
+
+
+@pytest.mark.asyncio
+async def test_batch_indexer_indexes_non_markdown_files(
+    app_config,
+    entity_service,
+    entity_repository,
+    relation_repository,
+    search_service,
+    file_service,
+    project_config,
+):
+    pdf_path = "assets/doc.pdf"
+    image_path = "assets/image.png"
+    await _create_file(project_config.home / pdf_path, b"%PDF-1.4 test")
+    await _create_file(project_config.home / image_path, b"\x89PNG\r\n\x1a\nrest")
+
+    files = {
+        pdf_path: await _load_input(file_service, pdf_path),
+        image_path: await _load_input(file_service, image_path),
+    }
+    batch_indexer = _make_batch_indexer(
+        app_config,
+        entity_service,
+        entity_repository,
+        relation_repository,
+        search_service,
+        file_service,
+    )
+
+    result = await batch_indexer.index_files(
+        files,
+        max_concurrent=2,
+        parse_max_concurrent=2,
+    )
+
+    assert {indexed.path for indexed in result.indexed} == {pdf_path, image_path}
+    assert all(indexed.markdown_content is None for indexed in result.indexed)
+
+    pdf_entity = await entity_repository.get_by_file_path(pdf_path)
+    image_entity = await entity_repository.get_by_file_path(image_path)
+    assert pdf_entity is not None
+    assert pdf_entity.content_type == "application/pdf"
+    assert image_entity is not None
+    assert image_entity.content_type == "image/png"
+
+
+@pytest.mark.asyncio
+async def test_batch_indexer_resolves_relations_and_refreshes_search(
+    app_config,
+    entity_service,
+    entity_repository,
+    relation_repository,
+    search_service,
+    search_repository,
+    file_service,
+    project_config,
+):
+    source_path = "notes/source.md"
+    target_path = "notes/target.md"
+    await _create_file(
+        project_config.home / source_path,
+        dedent(
+            """
+            ---
+            title: Source
+            type: note
+            ---
+            # Source
+
+            - depends_on [[Target]]
+            """
+        ).strip(),
+    )
+    await _create_file(
+        project_config.home / target_path,
+        dedent(
+            """
+            ---
+            title: Target
+            type: note
+            ---
+            # Target
+            """
+        ).strip(),
+    )
+
+    files = {
+        source_path: await _load_input(file_service, source_path),
+        target_path: await _load_input(file_service, target_path),
+    }
+    batch_indexer = _make_batch_indexer(
+        app_config,
+        entity_service,
+        entity_repository,
+        relation_repository,
+        search_service,
+        file_service,
+    )
+
+    result = await batch_indexer.index_files(
+        files,
+        max_concurrent=2,
+        parse_max_concurrent=2,
+    )
+
+    source = await entity_repository.get_by_file_path(source_path)
+    target = await entity_repository.get_by_file_path(target_path)
+    assert source is not None
+    assert target is not None
+    assert len(source.outgoing_relations) == 1
+    assert source.outgoing_relations[0].to_id == target.id
+    assert result.relations_unresolved == 0
+    assert result.search_indexed == 2
+
+    relation_rows = await search_repository.execute_query(
+        text(
+            "SELECT COUNT(*) FROM search_index "
+            "WHERE entity_id = :entity_id AND type = 'relation' AND to_id IS NOT NULL"
+        ),
+        {"entity_id": source.id},
+    )
+    assert relation_rows.scalar_one() == 1
+
+
+@pytest.mark.asyncio
+async def test_batch_indexer_assigns_unique_permalinks_for_batch_local_conflicts(
+    app_config,
+    entity_service,
+    entity_repository,
+    relation_repository,
+    search_service,
+    file_service,
+    project_config,
+):
+    path_one = "notes/basic memory bug.md"
+    path_two = "notes/basic-memory-bug.md"
+    await _create_file(
+        project_config.home / path_one,
+        dedent(
+            """
+            ---
+            title: Basic Memory Bug
+            type: note
+            ---
+            # Basic Memory Bug
+            """
+        ).strip(),
+    )
+    await _create_file(
+        project_config.home / path_two,
+        dedent(
+            """
+            ---
+            title: Basic Memory Bug Report
+            type: note
+            ---
+            # Basic Memory Bug Report
+            """
+        ).strip(),
+    )
+
+    files = {
+        path_one: await _load_input(file_service, path_one),
+        path_two: await _load_input(file_service, path_two),
+    }
+    original_contents = {
+        path: file.content.decode("utf-8")
+        for path, file in files.items()
+        if file.content is not None
+    }
+    batch_indexer = _make_batch_indexer(
+        app_config,
+        entity_service,
+        entity_repository,
+        relation_repository,
+        search_service,
+        file_service,
+    )
+
+    result = await batch_indexer.index_files(
+        files,
+        max_concurrent=2,
+        parse_max_concurrent=2,
+    )
+
+    assert result.errors == []
+    indexed_by_path = {indexed.path: indexed for indexed in result.indexed}
+    assert indexed_by_path[path_one].markdown_content is not None
+    assert indexed_by_path[path_two].markdown_content is not None
+    assert indexed_by_path[path_one].markdown_content != original_contents[path_one]
+    assert indexed_by_path[path_two].markdown_content != original_contents[path_two]
+    assert indexed_by_path[path_one].markdown_content == await file_service.read_file_content(
+        path_one
+    )
+    assert indexed_by_path[path_two].markdown_content == await file_service.read_file_content(
+        path_two
+    )
+
+    entities = await entity_repository.find_all()
+    assert len(entities) == 2
+    permalinks = [entity.permalink for entity in entities if entity.permalink]
+    assert len(set(permalinks)) == 2
+
+
+@pytest.mark.asyncio
+async def test_batch_indexer_uses_parsed_markdown_body_for_malformed_frontmatter_delimiters(
+    app_config,
+    entity_service,
+    entity_repository,
+    relation_repository,
+    search_service,
+    file_service,
+    project_config,
+):
+    app_config.disable_permalinks = True
+    app_config.ensure_frontmatter_on_sync = False
+
+    path = "notes/malformed.md"
+    malformed_content = dedent(
+        """
+        ---
+        this is not valid frontmatter
+        # Malformed Frontmatter
+
+        The parser should still index this file.
+        """
+    ).strip()
+    await _create_file(project_config.home / path, malformed_content)
+
+    files = {path: await _load_input(file_service, path)}
+    batch_indexer = _make_batch_indexer(
+        app_config,
+        entity_service,
+        entity_repository,
+        relation_repository,
+        search_service,
+        file_service,
+    )
+
+    result = await batch_indexer.index_files(
+        files,
+        max_concurrent=1,
+        parse_max_concurrent=1,
+    )
+
+    # Trigger: malformed frontmatter should pass through without normalization.
+    # Why: Windows can still surface that unchanged file with CRLF line endings.
+    # Outcome: compare the indexed markdown to the persisted file content, not the LF
+    #          test literal used to create it.
+    persisted_content = (project_config.home / path).read_bytes().decode("utf-8")
+
+    assert result.errors == []
+    assert len(result.indexed) == 1
+    assert result.indexed[0].markdown_content == persisted_content
+
+    entity = await entity_repository.get_by_file_path(path)
+    assert entity is not None
+
+
+@pytest.mark.asyncio
+async def test_batch_indexer_re_raises_fatal_sync_errors(
+    app_config,
+    entity_service,
+    entity_repository,
+    relation_repository,
+    search_service,
+    file_service,
+):
+    batch_indexer = _make_batch_indexer(
+        app_config,
+        entity_service,
+        entity_repository,
+        relation_repository,
+        search_service,
+        file_service,
+    )
+
+    async def fatal_worker(path: str) -> str:
+        raise SyncFatalError(f"fatal batch failure for {path}")
+
+    with pytest.raises(SyncFatalError, match="fatal batch failure"):
+        await batch_indexer._run_bounded(
+            ["notes/fatal.md"],
+            limit=1,
+            worker=fatal_worker,
+        )

tests/indexing/test_batching.py

@@ -0,0 +1,85 @@
+"""Tests for deterministic indexing batch planning."""
+
+from basic_memory.indexing import IndexFileMetadata
+from basic_memory.indexing.batching import build_index_batches
+
+
+def test_build_index_batches_respects_max_files() -> None:
+    metadata = {
+        f"note-{index}.md": IndexFileMetadata(path=f"note-{index}.md", size=10)
+        for index in range(5)
+    }
+
+    batches = build_index_batches(
+        list(metadata),
+        metadata,
+        max_files=2,
+        max_bytes=10_000,
+    )
+
+    assert [batch.paths for batch in batches] == [
+        ["note-0.md", "note-1.md"],
+        ["note-2.md", "note-3.md"],
+        ["note-4.md"],
+    ]
+
+
+def test_build_index_batches_respects_max_bytes() -> None:
+    metadata = {
+        "a.md": IndexFileMetadata(path="a.md", size=30),
+        "b.md": IndexFileMetadata(path="b.md", size=40),
+        "c.md": IndexFileMetadata(path="c.md", size=50),
+    }
+
+    batches = build_index_batches(
+        ["c.md", "a.md", "b.md"],
+        metadata,
+        max_files=10,
+        max_bytes=70,
+    )
+
+    assert [(batch.paths, batch.total_bytes) for batch in batches] == [
+        (["a.md", "b.md"], 70),
+        (["c.md"], 50),
+    ]
+
+
+def test_build_index_batches_puts_giant_file_in_single_file_batch() -> None:
+    metadata = {
+        "alpha.md": IndexFileMetadata(path="alpha.md", size=10),
+        "giant.md": IndexFileMetadata(path="giant.md", size=500),
+        "omega.md": IndexFileMetadata(path="omega.md", size=10),
+    }
+
+    batches = build_index_batches(
+        list(metadata),
+        metadata,
+        max_files=10,
+        max_bytes=100,
+    )
+
+    assert [(batch.paths, batch.total_bytes) for batch in batches] == [
+        (["alpha.md"], 10),
+        (["giant.md"], 500),
+        (["omega.md"], 10),
+    ]
+
+
+def test_build_index_batches_is_deterministic() -> None:
+    metadata = {
+        "notes/b.md": IndexFileMetadata(path="notes/b.md", size=10),
+        "notes/a.md": IndexFileMetadata(path="notes/a.md", size=10),
+        "notes/c.md": IndexFileMetadata(path="notes/c.md", size=10),
+    }
+
+    batches = build_index_batches(
+        ["notes/c.md", "notes/a.md", "notes/b.md"],
+        metadata,
+        max_files=2,
+        max_bytes=1_000,
+    )
+
+    assert [batch.paths for batch in batches] == [
+        ["notes/a.md", "notes/b.md"],
+        ["notes/c.md"],
+    ]

tests/markdown/test_date_frontmatter_parsing.py

@@ -358,4 +358,5 @@ async def test_parse_file_with_reserved_frontmatter_field_content(tmp_path):
     assert entity_markdown.frontmatter.metadata.get("content") == "Template for topic notes"
     assert entity_markdown.frontmatter.metadata.get("handler") == "some-handler-value"
     # The actual body content should be parsed correctly
+    assert entity_markdown.content is not None
     assert "Template Body" in entity_markdown.content

tests/markdown/test_entity_parser_error_handling.py

@@ -75,6 +75,7 @@ async def test_parse_file_with_completely_invalid_yaml(tmp_path):
     assert result.frontmatter.title == "broken_yaml"  # Default from filename
     assert result.frontmatter.type == "note"  # Default type
     # Content should include the whole file since frontmatter parsing failed
+    assert result.content is not None
     assert "# Content" in result.content
 
 
@@ -374,6 +375,7 @@ async def test_frontmatter_roundtrip_preserves_user_metadata(tmp_path):
     assert result.frontmatter.type == "litnote"  # NOT overwritten to "note"
     assert "citekey" in result.frontmatter.metadata
     assert result.frontmatter.metadata["citekey"] == "authorTitleYear2024"
+    assert result.content is not None
 
     # Simulate what write_frontmatter does
     post = frontmatter.Post(result.content, **result.frontmatter.metadata)

tests/markdown/test_markdown_processor.py

@@ -141,6 +141,7 @@ async def test_update_preserves_content(markdown_processor: MarkdownProcessor, t
     result = await markdown_processor.read_file(path)
 
     # Original content preserved
+    assert result.content is not None
     assert "Original content here." in result.content
 
     # Both observations present

tests/markdown/test_observation_edge_cases.py

@@ -28,6 +28,7 @@ def test_invalid_context():
     tokens = md.parse("- [test] Content (unclosed")
     token = next(t for t in tokens if t.type == "inline")
     obs = parse_observation(token)
+    assert obs is not None
     assert obs["content"] == "Content (unclosed"
     assert obs["context"] is None
 
@@ -35,6 +36,7 @@ def test_invalid_context():
     tokens = md.parse("- [test] Content (with) extra) parens)")
     token = next(t for t in tokens if t.type == "inline")
     obs = parse_observation(token)
+    assert obs is not None
     assert obs["content"] == "Content"
     assert obs["context"] == "with) extra) parens"
 
@@ -48,6 +50,7 @@ def test_complex_format():
     token = next(t for t in tokens if t.type == "inline")
 
     obs = parse_observation(token)
+    assert obs is not None
     assert obs["category"] == "complex test"
     assert set(obs["tags"]) == {"tag1", "tag2", "tag3"}
     assert obs["content"] == "This is #tag1#tag2 with #tag3 content"
@@ -55,6 +58,7 @@ def test_complex_format():
     # Pydantic model validation
     observation = Observation.model_validate(obs)
     assert observation.category == "complex test"
+    assert observation.tags is not None
     assert set(observation.tags) == {"tag1", "tag2", "tag3"}
     assert observation.content == "This is #tag1#tag2 with #tag3 content"
 
@@ -99,6 +103,7 @@ def test_unicode_content():
     tokens = md.parse("- [test] Emoji test 👍 #emoji #test (Testing emoji)")
     token = next(t for t in tokens if t.type == "inline")
     obs = parse_observation(token)
+    assert obs is not None
     assert "👍" in obs["content"]
     assert "emoji" in obs["tags"]
 
@@ -106,6 +111,7 @@ def test_unicode_content():
     tokens = md.parse("- [中文] Chinese text 测试 #language (Script test)")
     token = next(t for t in tokens if t.type == "inline")
     obs = parse_observation(token)
+    assert obs is not None
     assert obs["category"] == "中文"
     assert "测试" in obs["content"]
 
@@ -113,6 +119,7 @@ def test_unicode_content():
     tokens = md.parse("- [test] Mixed 中文 and 👍 #mixed")
     token = next(t for t in tokens if t.type == "inline")
     obs = parse_observation(token)
+    assert obs is not None
     assert "中文" in obs["content"]
     assert "👍" in obs["content"]
 

tests/markdown/test_parser_edge_cases.py

@@ -41,6 +41,7 @@ async def test_unicode_content(tmp_path):
 
     assert "测试" in entity.frontmatter.metadata["tags"]
     assert "chinese" not in entity.frontmatter.metadata["tags"]
+    assert entity.content is not None
     assert "🧪" in entity.content
 
     # Verify Unicode in observations
@@ -176,6 +177,28 @@ async def test_malformed_frontmatter(tmp_path):
     assert entity.frontmatter.permalink is None
 
 
+@pytest.mark.asyncio
+async def test_null_bytes_stripped(tmp_path):
+    """Test that null bytes are stripped from content before parsing.
+
+    PostgreSQL rejects null bytes (0x00) in text columns. Some files
+    (e.g. Claude agent definitions) can contain embedded nulls.
+    """
+    content = "---\ntitle: Test\ntype: note\n---\n\nSome content\x00with nulls\x00inside\n"
+
+    parser = EntityParser(tmp_path)
+    entity = await parser.parse_markdown_content(
+        file_path=tmp_path / "nulls.md",
+        content=content,
+    )
+
+    assert entity.content is not None
+    assert "\x00" not in entity.content
+    assert "Some content" in entity.content
+    assert "with nulls" in entity.content
+    assert "inside" in entity.content
+
+
 @pytest.mark.asyncio
 async def test_file_not_found():
     """Test handling of non-existent files."""