fix(core): default fastembed cache to ~/.basic-memory/fastembed_cache

FastEmbed's own default of /tmp/fastembed_cache is ephemeral in sandboxed
runtimes like Codex CLI where /tmp is wiped between invocations, causing
ONNXRuntimeError: NO_SUCHFILE on every subsequent semantic search or sync.

Add _default_fastembed_cache_dir() that mirrors the existing data_dir_path
logic (honors BASIC_MEMORY_CONFIG_DIR for isolated test environments) and
use it as default_factory for semantic_embedding_cache_dir. The field stays
str | None so users can explicitly set null to restore FastEmbed's own default.

Fixes #741. Related to #681.

Co-authored-by: Drew Cain <groksrc@users.noreply.github.com>
Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

.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

.github/workflows/test.yml

@@ -6,7 +6,6 @@ concurrency:
 
 on:
   push:
-    branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
 
@@ -52,7 +51,6 @@ jobs:
   test-sqlite-unit:
     name: Test SQLite Unit (${{ matrix.os }}, Python ${{ matrix.python-version }})
     timeout-minutes: 30
-    needs: [static-checks]
     strategy:
       fail-fast: false
       matrix:
@@ -99,7 +97,6 @@ jobs:
   test-sqlite-integration:
     name: Test SQLite Integration (${{ matrix.os }}, Python ${{ matrix.python-version }})
     timeout-minutes: 45
-    needs: [static-checks]
     strategy:
       fail-fast: false
       matrix:
@@ -146,7 +143,6 @@ jobs:
   test-postgres-unit:
     name: Test Postgres Unit (Python ${{ matrix.python-version }})
     timeout-minutes: 30
-    needs: [static-checks]
     strategy:
       fail-fast: false
       matrix:
@@ -155,8 +151,22 @@ jobs:
           - python-version: "3.13"
           - python-version: "3.14"
     runs-on: ubuntu-latest
-
-    # Note: No services section needed - testcontainers handles Postgres in Docker
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: basic_memory_user
+          POSTGRES_PASSWORD: dev_password
+          POSTGRES_DB: basic_memory_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U basic_memory_user -d basic_memory_test"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      BASIC_MEMORY_TEST_POSTGRES_URL: postgresql://basic_memory_user:dev_password@127.0.0.1:5432/basic_memory_test
 
     steps:
       - uses: actions/checkout@v4
@@ -190,7 +200,6 @@ jobs:
   test-postgres-integration:
     name: Test Postgres Integration (Python ${{ matrix.python-version }})
     timeout-minutes: 45
-    needs: [static-checks]
     strategy:
       fail-fast: false
       matrix:
@@ -199,8 +208,22 @@ jobs:
           - python-version: "3.13"
           - python-version: "3.14"
     runs-on: ubuntu-latest
-
-    # Note: No services section needed - testcontainers handles Postgres in Docker
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: basic_memory_user
+          POSTGRES_PASSWORD: dev_password
+          POSTGRES_DB: basic_memory_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U basic_memory_user -d basic_memory_test"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      BASIC_MEMORY_TEST_POSTGRES_URL: postgresql://basic_memory_user:dev_password@127.0.0.1:5432/basic_memory_test
 
     steps:
       - uses: actions/checkout@v4
@@ -234,7 +257,6 @@ jobs:
   test-semantic:
     name: Test Semantic (Python 3.12)
     timeout-minutes: 45
-    needs: [static-checks]
     runs-on: ubuntu-latest
 
     steps:

AGENTS.md

@@ -22,16 +22,16 @@ See the [README.md](README.md) file for a project overview.
 - Run unit tests (Postgres): `just test-unit-postgres`
 - Run integration tests (SQLite): `just test-int-sqlite`
 - Run integration tests (Postgres): `just test-int-postgres`
-- Run impacted tests: `just testmon` (pytest-testmon)
+- Run impacted tests: `just testmon` (pytest-testmon; only tests affected by changed code)
 - Run MCP smoke test: `just test-smoke`
-- Fast local loop: `just fast-check`
+- Fast local loop: `just fast-check` (default iteration flow)
 - Local consistency check: `just doctor`
 - Generate HTML coverage: `just coverage`
 - Single test: `pytest tests/path/to/test_file.py::test_function_name`
 - Run benchmarks: `pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"`
 - Lint: `just lint` or `ruff check . --fix`
-- Type check: `just typecheck` or `uv run pyright`
-- Type check (supplemental): `just typecheck-ty` or `uv run ty check src/`
+- Type check: `just typecheck` or `uv run ty check src tests test-int`
+- Type check (pyright): `just typecheck-pyright` or `uv run pyright`
 - Format: `just format` or `uv run ruff format .`
 - Run all code checks: `just check` (runs lint, format, typecheck, test)
 - Create db migration: `just migration "Your migration message"`
@@ -48,10 +48,12 @@ See the [README.md](README.md) file for a project overview.
 ### Code/Test/Verify Loop (fast path)
 
 1) **Code:** make changes.
-2) **Test:** `just fast-check` (lint/format/typecheck + impacted tests + MCP smoke).
+2) **Test:** `just fast-check` (lint/format/typecheck + pytest-testmon impacted tests for changed code).
 3) **Verify:** `just doctor` (end-to-end file ↔ DB loop in a temp project).
 4) **Full gate (when needed):** `just test` or `just check` for SQLite + Postgres.
 
+Run `just test-smoke` when you specifically need the MCP smoke flow.
+
 If testmon is “cold,” the first run may be long. Subsequent runs get much faster.
 
 ### Test Structure
@@ -442,5 +444,9 @@ With GitHub integration, the development workflow includes:
 3. **Branch management** - Claude can create feature branches for implementations
 4. **Documentation maintenance** - Claude can keep documentation updated as the code evolves
 5. **Code Commits**: ALWAYS sign off commits with `git commit -s`
+6. **Pull Request Titles**: PR titles must follow the semantic format enforced by `.github/workflows/pr-title.yml`: `type(scope): summary`
+   - Allowed types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`
+   - Allowed scopes: `core`, `cli`, `api`, `mcp`, `sync`, `ui`, `deps`, `installer`
+   - Example: `fix(cli): propagate cloud workspace routing`
 
 This level of integration represents a new paradigm in AI-human collaboration, where the AI assistant becomes a full-fledged team member rather than just a tool for generating code snippets.

CHANGELOG.md

@@ -2,13 +2,211 @@
 
 ## Unreleased
 
+## v0.20.3 (2026-03-26)
+
+### Bug Fixes
+
+- **#698**: CLI cloud commands now use API key when configured
+  - `get_authenticated_headers()` only checked OAuth tokens, ignoring `config.cloud_api_key`
+  - All CLI cloud commands (`upload`, `status`, `snapshot`, `restore`, etc.) failed for API-key-only users while MCP tools worked fine
+  - Now mirrors the same credential priority as MCP: API key first, OAuth fallback
+  - Fixes `bm cloud upload --project` returning "project does not exist" when authenticated with `bmc_*` API key
+
+## v0.20.2 (2026-03-10)
+
+### Bug Fixes
+
+- Fix auto-update Homebrew detection: `brew outdated` exits 1 when a formula is outdated, not on error
+  - Previously treated exit code 1 as a failure, causing "Automatic update check failed" instead of detecting the available update
+
+## v0.20.1 (2026-03-10)
+
+### Bug Fixes
+
+- **#661**: Fix `bm project list` MCP column to show transport type (stdio/https) instead of DB presence
+  - Renamed "MCP (stdio)" column to "MCP"
+  - Shows actual routing mode: `stdio` for local, `https` for cloud projects
+  - Clears local path display for cloud-mode projects
+- **#662**: Invalidate config cache when file is modified by another process
+  - Adds mtime-based cache validation to `ConfigManager.load_config()`
+  - Long-lived processes (MCP stdio server) now detect external config changes
+  - Fixes `bm project set-cloud` having no effect on running MCP server
+
+## v0.20.0 (2026-03-10)
+
 ### Features
 
+- **#643**: Default-on auto-update system and `bm update` command
+  - Automatic background update checks for CLI installs (uv tool, Homebrew)
+  - Install-source detection (homebrew, uv_tool, uvx, unknown) with uvx skip behavior
+  - Periodic check gating via `auto_update_last_checked_at` + `update_check_interval` config
+  - Manager-specific update flows: Homebrew (`brew upgrade`) and uv tool (`uv tool upgrade`)
+  - Silent, non-blocking MCP behavior via daemon thread before server run
+  - Manual commands: `bm update` (force check + apply) and `bm update --check` (check only)
+  - New config fields: `auto_update`, `update_check_interval`, `auto_update_last_checked_at`
+
+## v0.19.2 (2026-03-09)
+
+### Bug Fixes
+
+- **#657**: Coerce string params to list/dict in MCP tools
+  - MCP clients that serialize `list`/`dict` arguments as JSON strings no longer fail Pydantic validation
+  - Adds `BeforeValidator` coercion to `search_notes` (`entity_types`, `note_types`, `tags`, `metadata_filters`), `write_note` (`metadata`), and `canvas` (`nodes`, `edges`)
+- **#655**: Handle SQLite and Windows semantic search regressions
+  - Fix embedding status query for non-semantic SQLite databases
+  - Windows-safe log file rotation with per-process log filenames
+  - Robust `setup_logging` that handles all environments cleanly
+
+## v0.19.1 (2026-03-08)
+
+### Bug Fixes
+
+- **#649**: Enforce strict entity resolution in destructive MCP tools (`edit_note`, `move_note`, `delete_note`)
+  - Prevents fuzzy-match fallback from silently editing/moving/deleting the wrong note
+  - DST-related timeframe validation fix (round instead of truncate days)
+
+### Features
+
+- **#648**: Add `insert_before_section` and `insert_after_section` edit operations
+- Add `GET /knowledge/graph` endpoint for full graph visualization
+
+### Dependencies
+
+- Bump authlib from 1.6.6 to 1.6.7
+
+## v0.19.0 (2026-03-07)
+
+### Highlights
+
+- **Semantic vector search** for SQLite and Postgres with FastEmbed embeddings
+- **Schema system** for validating and inferring knowledge base structure
+- **Per-project cloud routing** with API key authentication
+- **Upgraded to FastMCP 3.0** with tool annotations
+- **CLI overhaul** with JSON output, workspace awareness, and project dashboard
+
+### Features
+
+- **#550**: Add semantic vector search for SQLite and Postgres
+  - FastEmbed-based embeddings with automatic backfill
+  - Hybrid search combining full-text and vector similarity
+  - Score-based fusion replacing RRF for better ranking
+  - `min_similarity` override for tuning search precision
+  - Semantic dependencies are now default, with optional extras fallback
+
+- **#549**: Schema system for Basic Memory
+  - `schema_infer` — infer schema from existing notes
+  - `schema_validate` — validate notes against a schema definition
+  - `schema_diff` — compare schemas across projects
+  - Frontmatter validation support (#597)
+  - Read schema definitions from file instead of stale DB metadata (#635)
+
+- **#555**: Per-project local/cloud routing with API key auth
+  - Individual projects route through cloud while others stay local
+  - `basic-memory cloud set-key` and `basic-memory project set-cloud/set-local`
+  - Stdio MCP honors per-project cloud routing (#590)
+
+- **#598**: Upgrade FastMCP 2.12.3 to 3.0.1 with tool annotations
+
+- **#585**: Add JSON output mode for MCP tools (default text)
+  - `--json` output for CLI commands for scripting and CI
+
+- **#576**: Add workspace selection flow for MCP and CLI
+  - Workspace-aware cloud project listing
+  - CLI refactoring for workspace support
+
+- **#544**: Project-prefixed permalinks and memory URL routing
+
+- **#632**: Add overwrite guard to `write_note` tool
+
+- **#614**: `edit_note` append/prepend auto-creates note if not found
+
+- **#609**: Richer content context in search results
+  - Return matched chunk text in search results (#601)
+  - Improved content hit rate
+
+- **#602**: Add `created_by` and `last_updated_by` user tracking to Entity
+
+- **#600**: Rename `entity_type` to `note_type` across codebase
+
+- **#574**: Add `display_name` and `is_private` to ProjectItem
+
+- **#569**: Expose `external_id` in EntityResponse and link resolver
+
+- **#567**: Isolate default SQLite DB by config dir
+
+- **#560**: Enable `default_project_mode` by default
+
+- **#559**: Add `basic-memory watch` CLI command
+
+- **#546**: Add cloud discovery touchpoints to CLI and MCP
+
+- **#572**: CLI analytics via Umami event collector
+
+- Replace project info with htop-inspired dashboard
+
+- Merge `search_by_metadata` into `search_notes` with optional query
+
 - Add `--strip-frontmatter` to `basic-memory tool read-note`
-  - Default behavior is unchanged: `content` still includes raw markdown with frontmatter.
-  - With `--strip-frontmatter`, both text and JSON modes return body-only markdown content.
-  - JSON output now includes an additive `frontmatter` field with parsed YAML metadata (or `null`
-    when no valid opening frontmatter block exists).
+
+- Add `destination_folder` parameter to `move_note` tool
+
+### Bug Fixes
+
+- **#644**: Fix default project resolution in cloud mode
+  - ChatGPT search/fetch tools broken in cloud mode
+  - `resolve_project_parameter` falls back to projects API
+
+- **#638**: Restore API backward compatibility for v0.18.x clients
+
+- **#637**: Create backup before config migration overwrites old format
+
+- **#636**: `list_workspaces` bypasses factory pattern on cloud MCP server
+
+- **#631**: `build_context` related_results schema validation failure
+
+- **#613**: Reduce excessive log volume by demoting per-request noise to DEBUG
+
+- **#612**: Handle quoted picoschema enum strings in YAML frontmatter
+
+- **#607**: Guard against closed streams in promo and missing vector tables
+
+- **#606**: Accept null for `expected_replacements` in `edit_note`
+
+- **#595**: `recent_activity` dedup and pagination across MCP tools
+
+- **#593**: Backend-specific distance-to-similarity conversion
+
+- **#582**: Use LinkResolver fallback in `build_context` for flexible identifier matching
+
+- **#577**: Replace RRF with score-based fusion in hybrid search
+
+- **#575**: Remove hardcoded "main" default from `default_project`
+
+- **#534**: Speed up `bm --version` startup
+
+- Fix semantic embeddings not generated on fresh DB or upgrade
+
+- Clarify `search_notes` parameter naming and fix `note_types` case sensitivity
+
+- Parse `tag:` prefix at MCP tool level to avoid hybrid search failure
+
+- Cap sqlite-vec knn k parameter at 4096 limit
+
+- Parameterize SQL queries in search repository type filters
+
+- Coerce list frontmatter values to strings for title and type fields
+
+- Avoid `Post(**metadata)` crash when frontmatter contains 'content' or 'handler' keys
+
+- Upgrade cryptography and python-multipart for security advisories
+
+### Internal
+
+- **#594**: Add `ty` as supplemental type checker
+- Batched vector sync orchestration across repositories
+- FastEmbed parallel guardrails and provider caching
+- Improved cloud CLI status and error messages
+- CI coverage and Postgres test fixes
 
 ## v0.18.5 (2026-02-13)
 

README.md

@@ -23,6 +23,18 @@ Basic Memory lets you build persistent knowledge through natural conversations w
 Claude, while keeping everything in simple Markdown files on your computer. It uses the Model Context Protocol (MCP) to
 enable any compatible LLM to read and write to your local knowledge base.
 
+## What's New in v0.19.0
+
+- **Semantic Vector Search** — find notes by meaning, not just keywords. Combines full-text and vector similarity for hybrid search with FastEmbed embeddings.
+- **Schema System** — infer, validate, and diff the structure of your knowledge base with `schema_infer`, `schema_validate`, and `schema_diff` tools.
+- **Per-Project Cloud Routing** — route individual projects through the cloud while others stay local, using API key authentication (`basic-memory project set-cloud`).
+- **FastMCP 3.0** — upgraded to FastMCP 3.0 with tool annotations for better client integration.
+- **CLI Overhaul** — JSON output mode (`--json`) for scripting, workspace-aware commands, and an htop-inspired project dashboard.
+- **Smarter Editing** — `edit_note` append/prepend auto-creates notes if they don't exist; `write_note` has an overwrite guard to prevent accidental data loss.
+- **Richer Search Results** — matched chunk text returned in search results for better context.
+
+See the full [CHANGELOG](CHANGELOG.md) for details.
+
 - Website: [basicmemory.com](https://basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme)
 - Documentation: [docs.basicmemory.com](https://docs.basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme)
 - Community: [Discord](https://discord.gg/tyvKNccgqN?utm_source=github&utm_medium=referral&utm_campaign=readme)
@@ -63,6 +75,36 @@ uv tool install basic-memory
 
 You can view shared context via files in `~/basic-memory` (default directory location).
 
+## Automatic Updates
+
+Basic Memory includes a default-on auto-update flow for CLI installs.
+
+- **Auto-install supported:** `uv tool` and Homebrew installs
+- **Default check interval:** every 24 hours (`86400` seconds)
+- **MCP-safe behavior:** update checks run silently in `basic-memory mcp` mode
+- **`uvx` behavior:** skipped (runtime is ephemeral and managed by `uvx`)
+
+Manual update commands:
+
+```bash
+# Check now and install if supported
+bm update
+
+# Check only, do not install
+bm update --check
+```
+
+Config options in `~/.basic-memory/config.json`:
+
+```json
+{
+  "auto_update": true,
+  "update_check_interval": 86400
+}
+```
+
+To disable automatic updates, set `"auto_update": false`.
+
 ## Why Basic Memory?
 
 Most LLM interactions are ephemeral - you ask a question, get an answer, and everything is forgotten. Each conversation

docs/logfire-instrumentation-strategy.md

@@ -0,0 +1,499 @@
+# Logfire Instrumentation Strategy
+
+## Why
+
+We want Logfire in Basic Memory for two specific use cases:
+
+1. Local development and performance investigation
+2. Cloud deployments where Basic Memory runs inside Basic Memory Cloud
+
+This instrumentation must be:
+
+- Disabled by default
+- Useful when enabled
+- Safe for local-first users
+- Searchable in Logfire over time
+
+The previous integration added telemetry, but it leaned too much on generic framework instrumentation. That created noisy spans with weak names and made the trace view harder to navigate. This strategy favors manual instrumentation around Basic Memory's real units of work.
+
+## Core Principles
+
+### 1. Default-off
+
+Basic Memory should ship with Logfire disabled unless the operator explicitly enables it.
+
+That means:
+
+- no required token for normal local usage
+- no surprise outbound telemetry
+- no behavior change for existing users
+
+### 2. Manual spans over automatic framework spans
+
+We should not rely on broad auto-instrumentation for FastAPI, MCP, SQLAlchemy, or HTTP as the primary experience.
+
+Why:
+
+- auto-generated span names are often generic
+- routes and middleware produce too many low-signal spans
+- it becomes harder to answer product questions like "why was `write_note` slow?" or "where did sync time go?"
+
+The preferred model is:
+
+- one meaningful root span per high-level operation
+- a small number of child spans for important phases
+- optional targeted instrumentation only where it adds clear value
+
+### 3. Logs must live inside traces
+
+Basic Memory already uses `loguru` pervasively. The Logfire integration should preserve that and make those logs visible inside the active trace/span context.
+
+If traces exist but the logs are detached from them, the integration is not doing its job.
+
+### 4. Stable names, selective attributes
+
+Span names should describe the operation class, not the specific input.
+
+Good:
+
+- `mcp.tool.write_note`
+- `sync.project.scan`
+- `search.execute`
+- `routing.resolve_project`
+
+Bad:
+
+- `Searching for "foo bar baz"`
+- `POST /v2/projects/123/search/`
+- `write note to /specs/api.md`
+
+Dynamic values belong in attributes, not in the span name.
+
+## What We Should Not Do
+
+### Avoid broad FastAPI auto-instrumentation
+
+We should not turn on `instrument_fastapi()` and treat that as the main telemetry story.
+
+It may still be useful in narrowly scoped debugging, but it should not define the production trace shape. The meaningful root spans should come from Basic Memory's own entrypoints and service boundaries.
+
+### Avoid per-file spans by default
+
+`sync` can process many files. A span per file will explode trace cardinality and make performance views noisy.
+
+Default behavior should be:
+
+- one span for the project sync
+- child spans for scan, move handling, delete handling, markdown sync batch, relation resolution, embedding sync, watermark update
+- per-file spans only for failures or very slow outliers
+
+### Avoid high-cardinality attributes on every span
+
+Do not attach large or highly variable values everywhere:
+
+- raw note content
+- file bodies
+- long search text
+- arbitrary metadata blobs
+- unique IDs that make every span shape distinct
+
+Prefer compact, queryable attributes:
+
+- `project_name`
+- `workspace_id`
+- `route_mode`
+- `scan_type`
+- `file_count`
+- `result_count`
+- `search_type`
+- `retrieval_mode`
+- `duration_ms`
+
+## Proposed Architecture
+
+Add a dedicated telemetry module in core Basic Memory, separate from logging setup.
+
+Suggested shape:
+
+```python
+# basic_memory/telemetry.py
+
+def configure_telemetry(service_name: str, *, enable_logfire: bool) -> None: ...
+def telemetry_enabled() -> bool: ...
+def span(name: str, **attrs): ...
+def bind_telemetry_context(**attrs): ...
+```
+
+This module should:
+
+- configure Logfire only when explicitly enabled
+- set up the Logfire `loguru` handler
+- expose lightweight helpers so application code does not import `logfire` directly everywhere
+- degrade cleanly to no-op behavior when disabled
+
+This keeps the rest of the codebase readable and makes it easy to reason about what telemetry is doing.
+
+## Logging Integration Strategy
+
+### Goal
+
+When a span is active, logs emitted through `loguru` during that operation should show up in the same trace.
+
+### Preferred design
+
+1. Configure Logfire once in the telemetry bootstrap
+2. Add the Logfire `loguru` handler to the existing `loguru` configuration
+3. At operation boundaries, bind stable contextual fields with `loguru`
+4. Let logs emitted inside the span inherit the active trace context
+
+### Context to bind
+
+Bind only the fields that help correlate work across the system:
+
+- `service_name`
+- `entrypoint`
+- `project_name`
+- `workspace_id`
+- `route_mode`
+- `tool_name`
+- `command_name`
+
+This binding should happen at the root of an operation, not deep in leaf functions.
+
+### Important nuance
+
+We should not try to encode the entire trace model into logger extras. The logger context should be a human-meaningful slice of the active operation. Trace linkage comes from the active Logfire/OpenTelemetry context; logger extras are there to improve searchability and readability.
+
+## Span Model
+
+### Root spans
+
+Each user-visible or system-visible operation should get one root span.
+
+Examples:
+
+- `cli.command.status`
+- `cli.command.project_sync`
+- `api.request.search`
+- `mcp.tool.write_note`
+- `mcp.tool.read_note`
+- `mcp.tool.search_notes`
+- `sync.project.run`
+- `db.semantic_backfill`
+
+### Child spans
+
+Child spans should represent real phases whose duration we care about.
+
+Examples:
+
+- `routing.client_session`
+- `routing.resolve_project`
+- `routing.resolve_workspace`
+- `api.search.execute`
+- `sync.project.scan`
+- `sync.project.detect_moves`
+- `sync.project.apply_changes`
+- `sync.project.resolve_relations`
+- `sync.project.sync_embeddings`
+- `sync.file.markdown`
+- `sync.file.regular`
+- `search.execute`
+- `search.relaxed_fts_retry`
+- `db.init`
+- `db.migrate`
+
+### Span naming rules
+
+- Use dot-separated names
+- Start with subsystem
+- Keep the verb at the end
+- Keep names stable across runs
+- Never include request-specific text in the span name
+
+## Attribute Taxonomy
+
+### Required attributes on root spans
+
+Every root span should have a small common set:
+
+- `service_name`
+- `entrypoint`
+- `project_name` when applicable
+- `workspace_id` when applicable
+- `route_mode` with values like `local_asgi`, `cloud_proxy`, `factory`
+
+### Operation-specific attributes
+
+Examples:
+
+For search:
+
+- `search_type`
+- `retrieval_mode`
+- `page`
+- `page_size`
+- `result_count`
+- `fallback_used`
+
+For sync:
+
+- `scan_type`
+- `force_full`
+- `new_count`
+- `modified_count`
+- `deleted_count`
+- `move_count`
+- `skipped_count`
+- `embeddings_enabled`
+
+For note operations:
+
+- `tool_name`
+- `note_type`
+- `directory`
+- `overwrite`
+- `output_format`
+
+### Attributes to avoid by default
+
+- full `query.text`
+- full note titles if they create privacy or cardinality issues
+- file content
+- raw frontmatter
+- raw HTTP bodies
+
+If we need richer payloads for a local debugging session, that should be an explicit temporary mode, not the default telemetry shape.
+
+## Instrumentation Plan By Layer
+
+### 1. Entrypoints
+
+Instrument these first:
+
+- `cli.app` callback and major commands
+- API lifespan and selected routers
+- MCP server lifespan
+- MCP tool entrypoints
+
+Why:
+
+- this establishes clean root spans
+- it gives us trace boundaries that match how users think about the product
+
+### 2. Routing and context resolution
+
+Instrument:
+
+- client routing decisions
+- workspace resolution
+- project resolution
+- default-project fallback
+
+Why:
+
+- Basic Memory has local/cloud/per-project routing logic
+- when something is slow or surprising, we need to know which path was taken
+
+### 3. Sync and indexing
+
+This is the highest-value area to instrument deeply.
+
+Instrument:
+
+- sync root
+- scan strategy decision
+- filesystem scan
+- move detection
+- delete handling
+- markdown sync phase
+- relation resolution
+- vector embedding sync
+- scan watermark update
+
+Why:
+
+- this is where performance work will happen
+- cloud and local both benefit from this visibility
+
+### 4. Search
+
+Instrument:
+
+- search execution
+- retrieval mode
+- relaxed FTS fallback
+- result shaping
+
+Why:
+
+- search is user-facing and latency-sensitive
+- hybrid/vector/FTS paths need to be distinguishable
+
+### 5. Database and initialization
+
+Instrument selectively:
+
+- DB init
+- migrations
+- semantic backfill
+- connection mode selection
+
+Avoid full automatic SQL span firehose by default.
+
+## Recommended Rollout Phases
+
+## Task List
+
+- [x] Phase 1: Bootstrap and config gating
+- [x] Phase 2: Root spans for entrypoints and primary operations
+- [x] Phase 3: Child spans for sync, search, and routing
+- [x] Phase 4: Failure-focused detail and final verification
+- [x] Phase 5: Loguru context binding and scoped context inheritance
+
+## Recommended Rollout Phases
+
+### Phase 1: Bootstrap and config gating
+
+Add:
+
+- telemetry bootstrap module
+- config/env gating
+- `loguru` + Logfire handler integration
+
+This gives immediate value with low noise.
+
+### Phase 2: Root spans for entrypoints and primary operations
+
+Add:
+
+- root spans for CLI, API, MCP, and main MCP tools
+- stable root attributes for project, workspace, route mode, and operation type
+
+This gives us clean top-level traces that match how users think about the product.
+
+### Phase 3: Child spans for sync, search, and routing
+
+Add child spans to:
+
+- sync
+- search
+- routing
+
+This is the main performance-investigation layer.
+
+### Phase 4: Failure-focused detail
+
+Add selective deeper spans/log enrichment for:
+
+- sync failures
+- relation resolution failures
+- slow file operations
+- cloud routing/auth failures
+
+This keeps normal traces clean while improving debuggability.
+
+### Phase 5: Loguru context binding and scoped context inheritance
+
+Add:
+
+- context-local telemetry state in `basic_memory.telemetry`
+- a shared `scope(...)` helper that opens a span and binds stable logger context together
+- context inheritance for routing, sync, and search so downstream `loguru` logs carry the active operation fields
+
+This makes the trace view and the log stream tell the same story without forcing logger rewrites across the codebase.
+
+## Local Dev Playbook
+
+The fastest way to sanity-check the current trace shape is:
+
+```bash
+LOGFIRE_TOKEN=lf_... just telemetry-smoke
+```
+
+What this does:
+
+- creates an isolated temp home, config dir, and project path
+- enables Logfire for the run
+- automatically exports to Logfire when `LOGFIRE_TOKEN` is present
+- defaults `BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=false` so the smoke run stays fast and trace-friendly
+- disables promo telemetry so the trace is about Basic Memory work, not analytics noise
+- runs a small CLI workflow:
+  - `project add`
+  - `tool write-note`
+  - `tool read-note`
+  - `tool edit-note`
+  - `tool build-context`
+  - `tool search-notes`
+  - `doctor`
+
+If you want to exercise the instrumentation without exporting anything upstream:
+
+```bash
+BASIC_MEMORY_LOGFIRE_SEND_TO_LOGFIRE=false just telemetry-smoke
+```
+
+If you want the smoke run to include vector or hybrid retrieval spans too:
+
+```bash
+LOGFIRE_TOKEN=lf_... BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=true just telemetry-smoke
+```
+
+The recipe sets `BASIC_MEMORY_LOGFIRE_ENVIRONMENT=telemetry-smoke` by default so these traces are easy to isolate in Logfire. Override it if you want the smoke traces grouped under a different environment name.
+
+### What to look for
+
+You should see a small set of comparable root spans rather than a framework-generated span forest:
+
+- `cli.command.project`
+- `cli.command.tool`
+- `mcp.tool.write_note`
+- `mcp.tool.read_note`
+- `mcp.tool.edit_note`
+- `mcp.tool.build_context`
+- `mcp.tool.search_notes`
+- `sync.project.run`
+
+You should also see correlated logs under those traces with stable fields like:
+
+- `project_name`
+- `route_mode`
+- `tool_name`
+- `entrypoint`
+
+### Expected nuance
+
+`doctor` creates its own temporary project on purpose. That means the sync trace will usually show a different project name than the `telemetry-smoke` write/search traces. That is fine for smoke testing because the goal is to confirm:
+
+- root span names are meaningful
+- scoped logs stay attached to the active trace
+- routing, tool, search, and sync phases are easy to distinguish
+
+## Validation Checklist
+
+We should consider the integration successful when the following are true:
+
+1. With telemetry disabled, Basic Memory behaves exactly as it does today.
+2. With telemetry enabled, one user action produces one obvious root span.
+3. Logs emitted during that action are visible inside the same trace.
+4. A search in Logfire for `mcp.tool.write_note` or `sync.project.run` returns comparable spans across runs.
+5. Trace views show phase timing clearly without drowning in framework noise.
+6. Sensitive payloads are not captured by default.
+
+## Immediate Implementation Direction
+
+When we start coding, the first pass should be:
+
+1. Add `basic_memory.telemetry`
+2. Add config/env switches for `enabled`, `send_to_logfire`, and service name
+3. Wire telemetry bootstrap into CLI, API, and MCP entrypoints
+4. Configure `loguru` to emit to both existing sinks and the Logfire handler when enabled
+5. Add manual root spans around:
+   - CLI commands
+   - API request handlers we care about
+   - MCP tool entrypoints
+   - sync root
+   - search root
+6. Add child spans to the sync and routing phases only after the root span model feels clean
+
+That gives us a strong foundation without repeating the earlier "turn on instrumentation everywhere" approach.

justfile

@@ -62,20 +62,20 @@ test-int-postgres:
     fi
 
 # Run tests impacted by recent changes (requires pytest-testmon)
+# Pass paths or node ids after `just testmon` to limit the candidate set further.
 testmon *args:
-    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov --testmon --testmon-forceselect {{args}}
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov --testmon {{args}}
 
 # Run MCP smoke test (fast end-to-end loop)
 test-smoke:
     BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m smoke test-int/mcp/test_smoke_integration.py
 
-# Fast local loop: lint, format, typecheck, impacted tests
+# Fast local loop: lint, format, typecheck, impacted tests via pytest-testmon
 fast-check:
     just fix
     just format
     just typecheck
     just testmon
-    just test-smoke
 
 # Reset Postgres test database (drops and recreates schema)
 # Useful when Alembic migration state gets out of sync during development
@@ -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:
@@ -205,6 +209,51 @@ doctor:
     BASIC_MEMORY_CONFIG_DIR="$TMP_CONFIG" \
     ./.venv/bin/python -m basic_memory.cli.main doctor --local
 
+# Run an isolated Logfire smoke workflow for local trace inspection
+telemetry-smoke:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    TMP_HOME=$(mktemp -d)
+    TMP_CONFIG=$(mktemp -d)
+    TMP_PROJECT=$(mktemp -d)
+    export HOME="$TMP_HOME"
+    export BASIC_MEMORY_ENV="${BASIC_MEMORY_ENV:-dev}"
+    export BASIC_MEMORY_HOME="$TMP_PROJECT/home-root"
+    export BASIC_MEMORY_CONFIG_DIR="$TMP_CONFIG"
+    export BASIC_MEMORY_NO_PROMOS=1
+    export BASIC_MEMORY_LOG_LEVEL="${BASIC_MEMORY_LOG_LEVEL:-INFO}"
+    export BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED="${BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED:-false}"
+    export BASIC_MEMORY_LOGFIRE_ENABLED="${BASIC_MEMORY_LOGFIRE_ENABLED:-true}"
+    export BASIC_MEMORY_LOGFIRE_ENVIRONMENT="${BASIC_MEMORY_LOGFIRE_ENVIRONMENT:-telemetry-smoke}"
+    if [[ -z "${BASIC_MEMORY_LOGFIRE_SEND_TO_LOGFIRE:-}" ]]; then
+        if [[ -n "${LOGFIRE_TOKEN:-}" ]]; then
+            export BASIC_MEMORY_LOGFIRE_SEND_TO_LOGFIRE=true
+        else
+            export BASIC_MEMORY_LOGFIRE_SEND_TO_LOGFIRE=false
+        fi
+    fi
+    mkdir -p "$BASIC_MEMORY_HOME"
+    echo "Telemetry smoke setup:"
+    echo "  logfire_enabled=$BASIC_MEMORY_LOGFIRE_ENABLED"
+    echo "  send_to_logfire=$BASIC_MEMORY_LOGFIRE_SEND_TO_LOGFIRE"
+    echo "  log_level=$BASIC_MEMORY_LOG_LEVEL"
+    echo "  semantic_search_enabled=$BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED"
+    echo "  logfire_environment=$BASIC_MEMORY_LOGFIRE_ENVIRONMENT"
+    echo "  project_path=$TMP_PROJECT"
+    ./.venv/bin/python -m basic_memory.cli.main project add telemetry-smoke "$TMP_PROJECT" --default --local
+    ./.venv/bin/python -m basic_memory.cli.main tool write-note --title "Telemetry Smoke" --folder notes --content "hello from smoke" --project telemetry-smoke --local
+    ./.venv/bin/python -m basic_memory.cli.main tool read-note notes/telemetry-smoke --project telemetry-smoke --local
+    ./.venv/bin/python -m basic_memory.cli.main tool edit-note notes/telemetry-smoke --operation append --content $'\n\nsmoke edit line' --project telemetry-smoke --local
+    ./.venv/bin/python -m basic_memory.cli.main tool build-context notes/telemetry-smoke --project telemetry-smoke --local --page-size 5 --max-related 5
+    ./.venv/bin/python -m basic_memory.cli.main tool search-notes telemetry --project telemetry-smoke --local
+    ./.venv/bin/python -m basic_memory.cli.main doctor --local
+    echo ""
+    echo "Telemetry smoke complete."
+    echo "Search Logfire for:"
+    echo "  service_name: basic-memory-cli"
+    echo "  environment: $BASIC_MEMORY_LOGFIRE_ENVIRONMENT"
+    echo "  span names: mcp.tool.write_note, mcp.tool.read_note, mcp.tool.edit_note, mcp.tool.build_context, mcp.tool.search_notes, sync.project.run"
+
 
 # Update all dependencies to latest versions
 update-deps:

llms-install.md

@@ -54,6 +54,22 @@ Or for a one-time sync:
 basic-memory sync
 ```
 
+### 4. Updating Basic Memory
+
+Basic Memory supports automatic updates by default for `uv tool` and Homebrew installs.
+
+For manual checks and upgrades:
+
+```bash
+# Check now and install if supported
+bm update
+
+# Check only, do not install
+bm update --check
+```
+
+To disable automatic updates, set `"auto_update": false` in `~/.basic-memory/config.json`.
+
 ## Configuration Options
 
 ### Custom Directory
@@ -125,4 +141,4 @@ If you encounter issues:
    cat ~/.basic-memory/basic-memory.log
    ```
 
-For more detailed information, refer to the [full documentation](https://memory.basicmachines.co/).
+For more detailed information, refer to the [full documentation](https://docs.basicmemory.com/).

pyproject.toml

@@ -58,6 +58,9 @@ Documentation = "https://github.com/basicmachines-co/basic-memory#readme"
 basic-memory = "basic_memory.cli.main:app"
 bm = "basic_memory.cli.main:app"
 
+[project.optional-dependencies]
+telemetry = ["logfire>=4.19.0"]
+
 [build-system]
 requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
 build-backend = "hatchling.build"
@@ -68,6 +71,12 @@ addopts = "--cov=basic_memory --cov-report term-missing"
 testpaths = ["tests", "test-int"]
 asyncio_mode = "strict"
 asyncio_default_fixture_loop_scope = "function"
+filterwarnings = [
+    "ignore:The @wait_container_is_ready decorator is deprecated.*:DeprecationWarning:testcontainers\\.core\\.waiting_utils",
+    "ignore:The default datetime adapter is deprecated as of Python 3\\.12.*:DeprecationWarning:aiosqlite\\.core",
+    "ignore:codecs\\.open\\(\\) is deprecated\\. Use open\\(\\) instead\\.:DeprecationWarning:frontmatter",
+    "ignore:Parsing dates involving a day of month without a year specified is ambiguous.*:DeprecationWarning:dateparser\\.utils\\.strptime",
+]
 markers = [
     "benchmark: Performance benchmark tests (deselect with '-m \"not benchmark\"')",
     "slow: Slow-running tests (deselect with '-m \"not slow\"')",
@@ -83,6 +92,7 @@ target-version = "py312"
 
 [dependency-groups]
 dev = [
+    "logfire>=4.19.0",
     "gevent>=24.11.1",
     "icecream>=2.1.3",
     "pytest>=8.3.4",

server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/basicmachines-co/basic-memory.git",
     "source": "github"
   },
-  "version": "0.18.5",
+  "version": "0.20.3",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "basic-memory",
-      "version": "0.18.5",
+      "version": "0.20.3",
       "runtimeHint": "uvx",
       "runtimeArguments": [
         {"type": "positional", "value": "basic-memory"},

skills-lock.json

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

src/basic_memory/__init__.py

@@ -1,7 +1,7 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
 # Package version - updated by release automation
-__version__ = "0.18.5"
+__version__ = "0.20.3"
 
 # API version for FastAPI - independent of package version
 __api_version__ = "v0"

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

@@ -25,6 +25,7 @@ from basic_memory.api.v2.routers.project_router import (
     list_projects,
     synchronize_projects,
 )
+from basic_memory import telemetry
 from basic_memory.config import init_api_logging
 from basic_memory.services.exceptions import EntityAlreadyExistsError
 from basic_memory.services.initialization import initialize_app
@@ -43,30 +44,39 @@ async def lifespan(app: FastAPI):  # pragma: no cover
     set_container(container)
     app.state.container = container
 
-    logger.info(f"Starting Basic Memory API (mode={container.mode.name})")
+    with telemetry.operation(
+        "api.lifecycle.startup",
+        entrypoint="api",
+        mode=container.mode.name.lower(),
+    ):
+        logger.info(f"Starting Basic Memory API (mode={container.mode.name})")
 
-    await initialize_app(container.config)
+        await initialize_app(container.config)
 
-    # Cache database connections in app state for performance
-    logger.info("Initializing database and caching connections...")
-    engine, session_maker = await container.init_database()
-    app.state.engine = engine
-    app.state.session_maker = session_maker
-    logger.info("Database connections cached in app state")
+        # Cache database connections in app state for performance
+        logger.info("Initializing database and caching connections...")
+        engine, session_maker = await container.init_database()
+        app.state.engine = engine
+        app.state.session_maker = session_maker
+        logger.info("Database connections cached in app state")
 
-    # Create and start sync coordinator (lifecycle centralized in coordinator)
-    sync_coordinator = container.create_sync_coordinator()
-    await sync_coordinator.start()
-    app.state.sync_coordinator = sync_coordinator
+        # Create and start sync coordinator (lifecycle centralized in coordinator)
+        sync_coordinator = container.create_sync_coordinator()
+        await sync_coordinator.start()
+        app.state.sync_coordinator = sync_coordinator
 
     # Proceed with startup
     yield
 
     # Shutdown - coordinator handles clean task cancellation
-    logger.info("Shutting down Basic Memory API")
-    await sync_coordinator.stop()
-
-    await container.shutdown_database()
+    with telemetry.operation(
+        "api.lifecycle.shutdown",
+        entrypoint="api",
+        mode=container.mode.name.lower(),
+    ):
+        logger.info("Shutting down Basic Memory API")
+        await sync_coordinator.stop()
+        await container.shutdown_database()
 
 
 # Initialize FastAPI app

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

@@ -13,6 +13,7 @@ Key improvements:
 from fastapi import APIRouter, HTTPException, BackgroundTasks, Depends, Response, Path, Query
 from loguru import logger
 
+from basic_memory import telemetry
 from basic_memory.deps import (
     EntityServiceV2ExternalDep,
     SearchServiceV2ExternalDep,
@@ -20,6 +21,7 @@ from basic_memory.deps import (
     ProjectConfigV2ExternalDep,
     AppConfigDep,
     EntityRepositoryV2ExternalDep,
+    RelationRepositoryV2ExternalDep,
     ProjectExternalIdPathDep,
     TaskSchedulerDep,
     FileServiceV2ExternalDep,
@@ -31,6 +33,9 @@ from basic_memory.schemas.v2 import (
     EntityResolveRequest,
     EntityResolveResponse,
     EntityResponseV2,
+    GraphEdge,
+    GraphNode,
+    GraphResponse,
     MoveEntityRequestV2,
     MoveDirectoryRequestV2,
     DeleteDirectoryRequestV2,
@@ -56,6 +61,50 @@ def _schedule_vector_sync_if_enabled(
         )
 
 
+## Graph endpoint
+
+
+@router.get("/graph", response_model=GraphResponse)
+async def get_graph(
+    project_id: ProjectExternalIdPathDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    relation_repository: RelationRepositoryV2ExternalDep,
+) -> GraphResponse:
+    """Return all entities and resolved relations for knowledge graph visualization.
+
+    Returns a flat node/edge structure optimized for rendering with graph libraries.
+    Only includes resolved relations (where to_id is not null).
+    """
+    logger.info("API v2 request: get_graph")
+
+    # Fetch all entities for this project
+    entities = await entity_repository.find_all(use_load_options=False)
+    nodes = [
+        GraphNode(
+            external_id=entity.external_id,
+            title=entity.title,
+            note_type=entity.note_type,
+            file_path=entity.file_path,
+        )
+        for entity in entities
+    ]
+
+    # Fetch all resolved relations (to_id is not null) with eager-loaded entities
+    relations = await relation_repository.find_all()
+    edges = [
+        GraphEdge(
+            from_id=relation.from_entity.external_id,
+            to_id=relation.to_entity.external_id,
+            relation_type=relation.relation_type,
+        )
+        for relation in relations
+        if relation.to_entity is not None
+    ]
+
+    logger.info(f"API v2 response: graph with {len(nodes)} nodes and {len(edges)} edges")
+    return GraphResponse(nodes=nodes, edges=edges)
+
+
 ## Resolution endpoint
 
 
@@ -94,47 +143,66 @@ async def resolve_identifier(
             "resolution_method": "permalink"
         }
     """
-    logger.info(f"API v2 request: resolve_identifier for '{data.identifier}'")
+    with telemetry.operation(
+        "api.request.knowledge.resolve_entity",
+        entrypoint="api",
+        domain="knowledge",
+        action="resolve_entity",
+    ):
+        logger.info(f"API v2 request: resolve_identifier for '{data.identifier}'")
 
-    # Try to resolve by external_id first
-    entity = await entity_repository.get_by_external_id(data.identifier)
-    resolution_method = "external_id" if entity else "search"
+        with telemetry.scope(
+            "api.knowledge.resolve_entity.lookup_entity",
+            domain="knowledge",
+            action="resolve_entity",
+            phase="lookup_entity",
+        ):
+            entity = await entity_repository.get_by_external_id(data.identifier)
+        resolution_method = "external_id" if entity else "search"
 
-    # If not found by external_id, try other resolution methods
-    # Pass source_path for context-aware resolution (prefers notes closer to source)
-    # Pass strict to control fuzzy search fallback (default False allows fuzzy matching)
-    if not entity:
-        entity = await link_resolver.resolve_link(
-            data.identifier, source_path=data.source_path, strict=data.strict
+        if not entity:
+            with telemetry.scope(
+                "api.knowledge.resolve_entity.resolve_link",
+                domain="knowledge",
+                action="resolve_entity",
+                phase="resolve_link",
+            ):
+                entity = await link_resolver.resolve_link(
+                    data.identifier, source_path=data.source_path, strict=data.strict
+                )
+            if entity:
+                if entity.permalink == data.identifier:
+                    resolution_method = "permalink"
+                elif entity.title == data.identifier:
+                    resolution_method = "title"
+                elif entity.file_path == data.identifier:
+                    resolution_method = "path"
+                else:
+                    resolution_method = "search"
+
+        if not entity:
+            raise HTTPException(status_code=404, detail=f"Entity not found: '{data.identifier}'")
+
+        with telemetry.scope(
+            "api.knowledge.resolve_entity.shape_response",
+            domain="knowledge",
+            action="resolve_entity",
+            phase="shape_response",
+        ):
+            result = EntityResolveResponse(
+                external_id=entity.external_id,
+                entity_id=entity.id,
+                permalink=entity.permalink,
+                file_path=entity.file_path,
+                title=entity.title,
+                resolution_method=resolution_method,
+            )
+
+        logger.debug(
+            f"API v2 response: resolved '{data.identifier}' to external_id={result.external_id} via {resolution_method}"
         )
-        if entity:
-            # Determine resolution method
-            if entity.permalink == data.identifier:
-                resolution_method = "permalink"
-            elif entity.title == data.identifier:
-                resolution_method = "title"
-            elif entity.file_path == data.identifier:
-                resolution_method = "path"
-            else:
-                resolution_method = "search"
 
-    if not entity:
-        raise HTTPException(status_code=404, detail=f"Entity not found: '{data.identifier}'")
-
-    result = EntityResolveResponse(
-        external_id=entity.external_id,
-        entity_id=entity.id,
-        permalink=entity.permalink,
-        file_path=entity.file_path,
-        title=entity.title,
-        resolution_method=resolution_method,
-    )
-
-    logger.debug(
-        f"API v2 response: resolved '{data.identifier}' to external_id={result.external_id} via {resolution_method}"
-    )
-
-    return result
+        return result
 
 
 ## Read endpoints
@@ -160,18 +228,36 @@ async def get_entity_by_id(
     Raises:
         HTTPException: 404 if entity not found
     """
-    logger.info(f"API v2 request: get_entity_by_id entity_id={entity_id}")
+    with telemetry.operation(
+        "api.request.knowledge.get_entity",
+        entrypoint="api",
+        domain="knowledge",
+        action="get_entity",
+    ):
+        logger.info(f"API v2 request: get_entity_by_id entity_id={entity_id}")
 
-    entity = await entity_repository.get_by_external_id(entity_id)
-    if not entity:
-        raise HTTPException(
-            status_code=404, detail=f"Entity with external_id '{entity_id}' not found"
-        )
+        with telemetry.scope(
+            "api.knowledge.get_entity.load_entity",
+            domain="knowledge",
+            action="get_entity",
+            phase="load_entity",
+        ):
+            entity = await entity_repository.get_by_external_id(entity_id)
+        if not entity:
+            raise HTTPException(
+                status_code=404, detail=f"Entity with external_id '{entity_id}' not found"
+            )
 
-    result = EntityResponseV2.model_validate(entity)
-    logger.info(f"API v2 response: external_id={entity_id}, title='{result.title}'")
+        with telemetry.scope(
+            "api.knowledge.get_entity.shape_response",
+            domain="knowledge",
+            action="get_entity",
+            phase="shape_response",
+        ):
+            result = EntityResponseV2.model_validate(entity)
+        logger.info(f"API v2 response: external_id={entity_id}, title='{result.title}'")
 
-    return result
+        return result
 
 
 ## Create endpoints
@@ -200,39 +286,92 @@ async def create_entity(
     Returns:
         Created entity with generated external_id (UUID) and file content
     """
-    logger.info(
-        "API v2 request", endpoint="create_entity", note_type=data.note_type, title=data.title
-    )
-
-    if fast:
-        entity = await entity_service.fast_write_entity(data)
-        task_scheduler.schedule(
-            "reindex_entity",
-            entity_id=entity.id,
-            project_id=project_id,
-        )
-    else:
-        entity = await entity_service.create_entity(data)
-        await search_service.index_entity(entity)
-        _schedule_vector_sync_if_enabled(
-            task_scheduler=task_scheduler,
-            app_config=app_config,
-            entity_id=entity.id,
-            project_id=project_id,
+    with telemetry.operation(
+        "api.request.knowledge.create_entity",
+        entrypoint="api",
+        domain="knowledge",
+        action="create_entity",
+        fast=fast,
+    ):
+        logger.info(
+            "API v2 request", endpoint="create_entity", note_type=data.note_type, title=data.title
         )
 
-    result = EntityResponseV2.model_validate(entity)
-    if fast:
-        result = result.model_copy(update={"observations": [], "relations": []})
+        with telemetry.scope(
+            "api.knowledge.create_entity.write_entity",
+            domain="knowledge",
+            action="create_entity",
+            phase="write_entity",
+            fast=fast,
+        ):
+            if fast:
+                entity = await entity_service.fast_write_entity(data)
+                written_content = None
+                search_content = None
+            else:
+                write_result = await entity_service.create_entity_with_content(data)
+                entity = write_result.entity
+                written_content = write_result.content
+                search_content = write_result.search_content
 
-    # Always read and return file content
-    content = await file_service.read_file_content(entity.file_path)
-    result = result.model_copy(update={"content": content})
+        if fast:
+            with telemetry.scope(
+                "api.knowledge.create_entity.enqueue_reindex",
+                domain="knowledge",
+                action="create_entity",
+                phase="enqueue_reindex",
+                fast=fast,
+            ):
+                task_scheduler.schedule(
+                    "reindex_entity",
+                    entity_id=entity.id,
+                    project_id=project_id,
+                )
+        else:
+            with telemetry.scope(
+                "api.knowledge.create_entity.search_index",
+                domain="knowledge",
+                action="create_entity",
+                phase="search_index",
+            ):
+                await search_service.index_entity(entity, content=search_content)
+            with telemetry.scope(
+                "api.knowledge.create_entity.vector_sync",
+                domain="knowledge",
+                action="create_entity",
+                phase="vector_sync",
+            ):
+                _schedule_vector_sync_if_enabled(
+                    task_scheduler=task_scheduler,
+                    app_config=app_config,
+                    entity_id=entity.id,
+                    project_id=project_id,
+                )
 
-    logger.info(
-        f"API v2 response: endpoint='create_entity' external_id={entity.external_id}, title={result.title}, permalink={result.permalink}, status_code=201"
-    )
-    return result
+        result = EntityResponseV2.model_validate(entity)
+        if fast:
+            result = result.model_copy(update={"observations": [], "relations": []})
+
+        with telemetry.scope(
+            "api.knowledge.create_entity.read_content",
+            domain="knowledge",
+            action="create_entity",
+            phase="read_content",
+            source="file" if fast else "memory",
+        ):
+            if fast:
+                content = await file_service.read_file_content(entity.file_path)
+            else:
+                # Non-fast writes already captured the markdown in memory. Reuse it here
+                # instead of re-reading the file; format_on_save is the one config that can
+                # still make the persisted file diverge because write_file only returns a checksum.
+                content = written_content
+        result = result.model_copy(update={"content": content})
+
+        logger.info(
+            f"API v2 response: endpoint='create_entity' external_id={entity.external_id}, title={result.title}, permalink={result.permalink}, status_code=201"
+        )
+        return result
 
 
 ## Update endpoints
@@ -267,61 +406,121 @@ async def update_entity_by_id(
     Returns:
         Updated entity with file content
     """
-    logger.info(f"API v2 request: update_entity_by_id entity_id={entity_id}")
+    with telemetry.operation(
+        "api.request.knowledge.update_entity",
+        entrypoint="api",
+        domain="knowledge",
+        action="update_entity",
+        fast=fast,
+    ):
+        logger.info(f"API v2 request: update_entity_by_id entity_id={entity_id}")
 
-    # Check if entity exists (external_id is the source of truth for v2)
-    existing = await entity_repository.get_by_external_id(entity_id)
-    created = existing is None
+        with telemetry.scope(
+            "api.knowledge.update_entity.load_entity",
+            domain="knowledge",
+            action="update_entity",
+            phase="load_entity",
+        ):
+            existing = await entity_repository.get_by_external_id(entity_id)
+        created = existing is None
 
-    if fast:
-        entity = await entity_service.fast_write_entity(data, external_id=entity_id)
-        response.status_code = 200 if existing else 201
-        task_scheduler.schedule(
-            "reindex_entity",
-            entity_id=entity.id,
-            project_id=project_id,
-            resolve_relations=created,
-        )
-    else:
-        if existing:
-            # Update the existing entity in-place to avoid path-based duplication
-            entity = await entity_service.update_entity(existing, data)
-            response.status_code = 200
-        else:
-            # Create new entity, then bind external_id to the requested UUID
-            entity = await entity_service.create_entity(data)
-            if entity.external_id != entity_id:
-                entity = await entity_repository.update(
-                    entity.id,
-                    {"external_id": entity_id},
+        with telemetry.scope(
+            "api.knowledge.update_entity.write_entity",
+            domain="knowledge",
+            action="update_entity",
+            phase="write_entity",
+            fast=fast,
+        ):
+            if fast:
+                entity = await entity_service.fast_write_entity(data, external_id=entity_id)
+                written_content = None
+                search_content = None
+                response.status_code = 200 if existing else 201
+            else:
+                if existing:
+                    write_result = await entity_service.update_entity_with_content(existing, data)
+                    entity = write_result.entity
+                    written_content = write_result.content
+                    search_content = write_result.search_content
+                    response.status_code = 200
+                else:
+                    write_result = await entity_service.create_entity_with_content(data)
+                    entity = write_result.entity
+                    written_content = write_result.content
+                    search_content = write_result.search_content
+                    if entity.external_id != entity_id:
+                        entity = await entity_repository.update(
+                            entity.id,
+                            {"external_id": entity_id},
+                        )
+                        # external_id fixup only changes the DB row. The file content is unchanged,
+                        # so the markdown captured during the write remains valid downstream.
+                        if not entity:
+                            raise HTTPException(
+                                status_code=404,
+                                detail=f"Entity with external_id '{entity_id}' not found",
+                            )
+                    response.status_code = 201
+
+        if fast:
+            with telemetry.scope(
+                "api.knowledge.update_entity.enqueue_reindex",
+                domain="knowledge",
+                action="update_entity",
+                phase="enqueue_reindex",
+                fast=fast,
+            ):
+                task_scheduler.schedule(
+                    "reindex_entity",
+                    entity_id=entity.id,
+                    project_id=project_id,
+                    resolve_relations=created,
+                )
+        else:
+            with telemetry.scope(
+                "api.knowledge.update_entity.search_index",
+                domain="knowledge",
+                action="update_entity",
+                phase="search_index",
+            ):
+                await search_service.index_entity(entity, content=search_content)
+            with telemetry.scope(
+                "api.knowledge.update_entity.vector_sync",
+                domain="knowledge",
+                action="update_entity",
+                phase="vector_sync",
+            ):
+                _schedule_vector_sync_if_enabled(
+                    task_scheduler=task_scheduler,
+                    app_config=app_config,
+                    entity_id=entity.id,
+                    project_id=project_id,
                 )
-                if not entity:
-                    raise HTTPException(
-                        status_code=404,
-                        detail=f"Entity with external_id '{entity_id}' not found",
-                    )
-            response.status_code = 201
 
-        await search_service.index_entity(entity)
-        _schedule_vector_sync_if_enabled(
-            task_scheduler=task_scheduler,
-            app_config=app_config,
-            entity_id=entity.id,
-            project_id=project_id,
+        result = EntityResponseV2.model_validate(entity)
+        if fast:
+            result = result.model_copy(update={"observations": [], "relations": []})
+
+        with telemetry.scope(
+            "api.knowledge.update_entity.read_content",
+            domain="knowledge",
+            action="update_entity",
+            phase="read_content",
+            source="file" if fast else "memory",
+        ):
+            if fast:
+                content = await file_service.read_file_content(entity.file_path)
+            else:
+                # Non-fast writes already captured the markdown in memory. Reuse it here
+                # instead of re-reading the file; format_on_save is the one config that can
+                # still make the persisted file diverge because write_file only returns a checksum.
+                content = written_content
+        result = result.model_copy(update={"content": content})
+
+        logger.info(
+            f"API v2 response: external_id={entity_id}, created={created}, status_code={response.status_code}"
         )
-
-    result = EntityResponseV2.model_validate(entity)
-    if fast:
-        result = result.model_copy(update={"observations": [], "relations": []})
-
-    # Always read and return file content
-    content = await file_service.read_file_content(entity.file_path)
-    result = result.model_copy(update={"content": content})
-
-    logger.info(
-        f"API v2 response: external_id={entity_id}, created={created}, status_code={response.status_code}"
-    )
-    return result
+        return result
 
 
 @router.patch("/entities/{entity_id}", response_model=EntityResponseV2)
@@ -353,69 +552,125 @@ async def edit_entity_by_id(
     Raises:
         HTTPException: 404 if entity not found, 400 if edit fails
     """
-    logger.info(
-        f"API v2 request: edit_entity_by_id entity_id={entity_id}, operation='{data.operation}'"
-    )
-
-    # Verify entity exists
-    entity = await entity_repository.get_by_external_id(entity_id)
-    if not entity:  # pragma: no cover
-        raise HTTPException(
-            status_code=404, detail=f"Entity with external_id '{entity_id}' not found"
-        )
-
-    try:
-        if fast:
-            updated_entity = await entity_service.fast_edit_entity(
-                entity=entity,
-                operation=data.operation,
-                content=data.content,
-                section=data.section,
-                find_text=data.find_text,
-                expected_replacements=data.expected_replacements,
-            )
-            task_scheduler.schedule(
-                "reindex_entity",
-                entity_id=updated_entity.id,
-                project_id=project_id,
-            )
-        else:
-            # Edit using the entity's permalink or path
-            identifier = entity.permalink or entity.file_path
-            updated_entity = await entity_service.edit_entity(
-                identifier=identifier,
-                operation=data.operation,
-                content=data.content,
-                section=data.section,
-                find_text=data.find_text,
-                expected_replacements=data.expected_replacements,
-            )
-
-            await search_service.index_entity(updated_entity)
-            _schedule_vector_sync_if_enabled(
-                task_scheduler=task_scheduler,
-                app_config=app_config,
-                entity_id=updated_entity.id,
-                project_id=project_id,
-            )
-
-        result = EntityResponseV2.model_validate(updated_entity)
-        if fast:
-            result = result.model_copy(update={"observations": [], "relations": []})
-
-        # Always read and return file content
-        content = await file_service.read_file_content(updated_entity.file_path)
-        result = result.model_copy(update={"content": content})
-
+    with telemetry.operation(
+        "api.request.knowledge.edit_entity",
+        entrypoint="api",
+        domain="knowledge",
+        action="edit_entity",
+        fast=fast,
+    ):
         logger.info(
-            f"API v2 response: external_id={entity_id}, operation='{data.operation}', status_code=200"
+            f"API v2 request: edit_entity_by_id entity_id={entity_id}, operation='{data.operation}'"
         )
 
-        return result
+        with telemetry.scope(
+            "api.knowledge.edit_entity.load_entity",
+            domain="knowledge",
+            action="edit_entity",
+            phase="load_entity",
+        ):
+            entity = await entity_repository.get_by_external_id(entity_id)
+        if not entity:  # pragma: no cover
+            raise HTTPException(
+                status_code=404, detail=f"Entity with external_id '{entity_id}' not found"
+            )
 
-    except Exception as e:
-        logger.error(f"Error editing entity {entity_id}: {e}")
-        raise HTTPException(status_code=400, detail=str(e))
+        try:
+            with telemetry.scope(
+                "api.knowledge.edit_entity.write_entity",
+                domain="knowledge",
+                action="edit_entity",
+                phase="write_entity",
+                fast=fast,
+            ):
+                if fast:
+                    updated_entity = await entity_service.fast_edit_entity(
+                        entity=entity,
+                        operation=data.operation,
+                        content=data.content,
+                        section=data.section,
+                        find_text=data.find_text,
+                        expected_replacements=data.expected_replacements,
+                    )
+                    written_content = None
+                    search_content = None
+                else:
+                    identifier = entity.permalink or entity.file_path
+                    write_result = await entity_service.edit_entity_with_content(
+                        identifier=identifier,
+                        operation=data.operation,
+                        content=data.content,
+                        section=data.section,
+                        find_text=data.find_text,
+                        expected_replacements=data.expected_replacements,
+                    )
+                    updated_entity = write_result.entity
+                    written_content = write_result.content
+                    search_content = write_result.search_content
+
+            if fast:
+                with telemetry.scope(
+                    "api.knowledge.edit_entity.enqueue_reindex",
+                    domain="knowledge",
+                    action="edit_entity",
+                    phase="enqueue_reindex",
+                    fast=fast,
+                ):
+                    task_scheduler.schedule(
+                        "reindex_entity",
+                        entity_id=updated_entity.id,
+                        project_id=project_id,
+                    )
+            else:
+                with telemetry.scope(
+                    "api.knowledge.edit_entity.search_index",
+                    domain="knowledge",
+                    action="edit_entity",
+                    phase="search_index",
+                ):
+                    await search_service.index_entity(updated_entity, content=search_content)
+                with telemetry.scope(
+                    "api.knowledge.edit_entity.vector_sync",
+                    domain="knowledge",
+                    action="edit_entity",
+                    phase="vector_sync",
+                ):
+                    _schedule_vector_sync_if_enabled(
+                        task_scheduler=task_scheduler,
+                        app_config=app_config,
+                        entity_id=updated_entity.id,
+                        project_id=project_id,
+                    )
+
+            result = EntityResponseV2.model_validate(updated_entity)
+            if fast:
+                result = result.model_copy(update={"observations": [], "relations": []})
+
+            with telemetry.scope(
+                "api.knowledge.edit_entity.read_content",
+                domain="knowledge",
+                action="edit_entity",
+                phase="read_content",
+                source="file" if fast else "memory",
+            ):
+                if fast:
+                    content = await file_service.read_file_content(updated_entity.file_path)
+                else:
+                    # Non-fast writes already captured the markdown in memory. Reuse it here
+                    # instead of re-reading the file; format_on_save is the one config that can
+                    # still make the persisted file diverge because write_file only returns a checksum.
+                    content = written_content
+            result = result.model_copy(update={"content": content})
+
+            logger.info(
+                f"API v2 response: external_id={entity_id}, operation='{data.operation}', status_code=200"
+            )
+
+            return result
+
+        except Exception as e:
+            logger.error(f"Error editing entity {entity_id}: {e}")
+            raise HTTPException(status_code=400, detail=str(e))
 
 
 ## Delete endpoints

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

@@ -9,6 +9,7 @@ from typing import Annotated, Optional
 from fastapi import APIRouter, Query, Path
 from loguru import logger
 
+from basic_memory import telemetry
 from basic_memory.deps import ContextServiceV2ExternalDep, EntityRepositoryV2ExternalDep
 from basic_memory.schemas.base import TimeFrame, parse_timeframe
 from basic_memory.schemas.memory import (
@@ -50,30 +51,55 @@ async def recent(
     Returns:
         GraphContext with recent activity and related entities
     """
-    # return all types by default
-    types = (
-        [SearchItemType.ENTITY, SearchItemType.RELATION, SearchItemType.OBSERVATION]
-        if not type
-        else type
-    )
+    with telemetry.operation(
+        "api.request.memory.recent_activity",
+        entrypoint="api",
+        domain="memory",
+        action="recent_activity",
+        page=page,
+        page_size=page_size,
+    ):
+        types = (
+            [SearchItemType.ENTITY, SearchItemType.RELATION, SearchItemType.OBSERVATION]
+            if not type
+            else type
+        )
 
-    logger.debug(
-        f"V2 Getting recent context for project {project_id}: `{types}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
-    )
-    # Parse timeframe
-    since = parse_timeframe(timeframe)
-    limit = page_size
-    offset = (page - 1) * page_size
+        logger.debug(
+            f"V2 Getting recent context for project {project_id}: `{types}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
+        )
+        since = parse_timeframe(timeframe)
+        limit = page_size
+        offset = (page - 1) * page_size
 
-    # Build context
-    context = await context_service.build_context(
-        types=types, depth=depth, since=since, limit=limit, offset=offset, max_related=max_related
-    )
-    recent_context = await to_graph_context(
-        context, entity_repository=entity_repository, page=page, page_size=page_size
-    )
-    logger.debug(f"V2 Recent context: {recent_context.model_dump_json()}")
-    return recent_context
+        with telemetry.scope(
+            "api.memory.recent_activity.build_context",
+            domain="memory",
+            action="recent_activity",
+            phase="build_context",
+            page=page,
+            page_size=page_size,
+        ):
+            context = await context_service.build_context(
+                types=types,
+                depth=depth,
+                since=since,
+                limit=limit,
+                offset=offset,
+                max_related=max_related,
+            )
+        with telemetry.scope(
+            "api.memory.recent_activity.shape_response",
+            domain="memory",
+            action="recent_activity",
+            phase="shape_response",
+            result_count=len(context.results),
+        ):
+            recent_context = await to_graph_context(
+                context, entity_repository=entity_repository, page=page, page_size=page_size
+            )
+        logger.debug(f"V2 Recent context: {recent_context.model_dump_json()}")
+        return recent_context
 
 
 # get_memory_context needs to be declared last so other paths can match
@@ -111,20 +137,46 @@ async def get_memory_context(
     Returns:
         GraphContext with the entity and its related context
     """
-    logger.debug(
-        f"V2 Getting context for project {project_id}, URI: `{uri}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
-    )
-    memory_url = normalize_memory_url(uri)
+    with telemetry.operation(
+        "api.request.memory.build_context",
+        entrypoint="api",
+        domain="memory",
+        action="build_context",
+        page=page,
+        page_size=page_size,
+    ):
+        logger.debug(
+            f"V2 Getting context for project {project_id}, URI: `{uri}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
+        )
+        memory_url = normalize_memory_url(uri)
 
-    # Parse timeframe
-    since = parse_timeframe(timeframe) if timeframe else None
-    limit = page_size
-    offset = (page - 1) * page_size
+        since = parse_timeframe(timeframe) if timeframe else None
+        limit = page_size
+        offset = (page - 1) * page_size
 
-    # Build context
-    context = await context_service.build_context(
-        memory_url, depth=depth, since=since, limit=limit, offset=offset, max_related=max_related
-    )
-    return await to_graph_context(
-        context, entity_repository=entity_repository, page=page, page_size=page_size
-    )
+        with telemetry.scope(
+            "api.memory.build_context.build_context",
+            domain="memory",
+            action="build_context",
+            phase="build_context",
+            page=page,
+            page_size=page_size,
+        ):
+            context = await context_service.build_context(
+                memory_url,
+                depth=depth,
+                since=since,
+                limit=limit,
+                offset=offset,
+                max_related=max_related,
+            )
+        with telemetry.scope(
+            "api.memory.build_context.shape_response",
+            domain="memory",
+            action="build_context",
+            phase="shape_response",
+            result_count=len(context.results),
+        ):
+            return await to_graph_context(
+                context, entity_repository=entity_repository, page=page, page_size=page_size
+            )

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

@@ -15,6 +15,7 @@ from pathlib import Path as PathLib
 from fastapi import APIRouter, HTTPException, Response, Path
 from loguru import logger
 
+from basic_memory import telemetry
 from basic_memory.deps import (
     ProjectConfigV2ExternalDep,
     FileServiceV2ExternalDep,
@@ -55,36 +56,62 @@ async def get_resource_content(
     Raises:
         HTTPException: 404 if entity or file not found
     """
-    logger.debug(f"V2 Getting content for project {project_id}, entity_id: {entity_id}")
+    with telemetry.operation(
+        "api.request.resource.get_content",
+        entrypoint="api",
+        domain="resource",
+        action="get_content",
+    ):
+        logger.debug(f"V2 Getting content for project {project_id}, entity_id: {entity_id}")
 
-    # Get entity by external_id
-    entity = await entity_repository.get_by_external_id(entity_id)
-    if not entity:
-        raise HTTPException(status_code=404, detail=f"Entity {entity_id} not found")
+        with telemetry.scope(
+            "api.resource.get_content.load_entity",
+            domain="resource",
+            action="get_content",
+            phase="load_entity",
+        ):
+            entity = await entity_repository.get_by_external_id(entity_id)
+        if not entity:
+            raise HTTPException(status_code=404, detail=f"Entity {entity_id} not found")
 
-    # Validate entity file path to prevent path traversal
-    project_path = PathLib(config.home)
-    if not validate_project_path(entity.file_path, project_path):
-        logger.error(  # pragma: no cover
-            f"Invalid file path in entity {entity.id}: {entity.file_path}"
-        )
-        raise HTTPException(  # pragma: no cover
-            status_code=500,
-            detail="Entity contains invalid file path",
-        )
+        with telemetry.scope(
+            "api.resource.get_content.validate_path",
+            domain="resource",
+            action="get_content",
+            phase="validate_path",
+        ):
+            project_path = PathLib(config.home)
+            if not validate_project_path(entity.file_path, project_path):
+                logger.error(  # pragma: no cover
+                    f"Invalid file path in entity {entity.id}: {entity.file_path}"
+                )
+                raise HTTPException(  # pragma: no cover
+                    status_code=500,
+                    detail="Entity contains invalid file path",
+                )
 
-    # Check file exists via file_service (for cloud compatibility)
-    if not await file_service.exists(entity.file_path):
-        raise HTTPException(  # pragma: no cover
-            status_code=404,
-            detail=f"File not found: {entity.file_path}",
-        )
+        with telemetry.scope(
+            "api.resource.get_content.ensure_exists",
+            domain="resource",
+            action="get_content",
+            phase="ensure_exists",
+        ):
+            if not await file_service.exists(entity.file_path):
+                raise HTTPException(  # pragma: no cover
+                    status_code=404,
+                    detail=f"File not found: {entity.file_path}",
+                )
 
-    # Read content via file_service as bytes (works with both local and S3)
-    content = await file_service.read_file_bytes(entity.file_path)
-    content_type = file_service.content_type(entity.file_path)
+        with telemetry.scope(
+            "api.resource.get_content.read_content",
+            domain="resource",
+            action="get_content",
+            phase="read_content",
+        ):
+            content = await file_service.read_file_bytes(entity.file_path)
+            content_type = file_service.content_type(entity.file_path)
 
-    return Response(content=content, media_type=content_type)
+        return Response(content=content, media_type=content_type)
 
 
 @router.post("", response_model=ResourceResponse)
@@ -112,74 +139,94 @@ async def create_resource(
     Raises:
         HTTPException: 400 for invalid file paths, 409 if file already exists
     """
-    try:
-        # Validate path to prevent path traversal attacks
-        project_path = PathLib(config.home)
-        if not validate_project_path(data.file_path, project_path):
-            logger.warning(
-                f"Invalid file path attempted: {data.file_path} in project {config.name}"
+    with telemetry.operation(
+        "api.request.resource.create",
+        entrypoint="api",
+        domain="resource",
+        action="create",
+    ):
+        try:
+            # Validate path to prevent path traversal attacks
+            project_path = PathLib(config.home)
+            if not validate_project_path(data.file_path, project_path):
+                logger.warning(
+                    f"Invalid file path attempted: {data.file_path} in project {config.name}"
+                )
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Invalid file path: {data.file_path}. "
+                    "Path must be relative and stay within project boundaries.",
+                )
+
+            existing_entity = await entity_repository.get_by_file_path(data.file_path)
+            if existing_entity:
+                raise HTTPException(
+                    status_code=409,
+                    detail=f"Resource already exists at {data.file_path} with entity_id {existing_entity.external_id}. "
+                    f"Use PUT /resource/{existing_entity.external_id} to update it.",
+                )
+
+            with telemetry.scope(
+                "api.resource.create.write_file",
+                domain="resource",
+                action="create",
+                phase="write_file",
+            ):
+                await file_service.ensure_directory(PathLib(data.file_path).parent)
+                checksum = await file_service.write_file(data.file_path, data.content)
+
+            with telemetry.scope(
+                "api.resource.create.read_metadata",
+                domain="resource",
+                action="create",
+                phase="read_metadata",
+            ):
+                file_metadata = await file_service.get_file_metadata(data.file_path)
+
+            file_name = PathLib(data.file_path).name
+            content_type = file_service.content_type(data.file_path)
+            note_type = "canvas" if data.file_path.endswith(".canvas") else "file"
+
+            entity = EntityModel(
+                external_id=str(uuid.uuid4()),
+                title=file_name,
+                note_type=note_type,
+                content_type=content_type,
+                file_path=data.file_path,
+                checksum=checksum,
+                created_at=file_metadata.created_at,
+                updated_at=file_metadata.modified_at,
             )
-            raise HTTPException(
-                status_code=400,
-                detail=f"Invalid file path: {data.file_path}. "
-                "Path must be relative and stay within project boundaries.",
+            with telemetry.scope(
+                "api.resource.create.upsert_entity",
+                domain="resource",
+                action="create",
+                phase="upsert_entity",
+            ):
+                entity = await entity_repository.add(entity)
+
+            with telemetry.scope(
+                "api.resource.create.search_index",
+                domain="resource",
+                action="create",
+                phase="search_index",
+            ):
+                await search_service.index_entity(entity)
+
+            return ResourceResponse(
+                entity_id=entity.id,
+                external_id=entity.external_id,
+                file_path=data.file_path,
+                checksum=checksum,
+                size=file_metadata.size,
+                created_at=file_metadata.created_at.timestamp(),
+                modified_at=file_metadata.modified_at.timestamp(),
             )
-
-        # Check if entity already exists
-        existing_entity = await entity_repository.get_by_file_path(data.file_path)
-        if existing_entity:
-            raise HTTPException(
-                status_code=409,
-                detail=f"Resource already exists at {data.file_path} with entity_id {existing_entity.external_id}. "
-                f"Use PUT /resource/{existing_entity.external_id} to update it.",
-            )
-
-        # Cloud compatibility: avoid assuming a local filesystem path.
-        # Delegate directory creation + writes to FileService (local or S3).
-        await file_service.ensure_directory(PathLib(data.file_path).parent)
-        checksum = await file_service.write_file(data.file_path, data.content)
-
-        # Get file info
-        file_metadata = await file_service.get_file_metadata(data.file_path)
-
-        # Determine file details
-        file_name = PathLib(data.file_path).name
-        content_type = file_service.content_type(data.file_path)
-        note_type = "canvas" if data.file_path.endswith(".canvas") else "file"
-
-        # Create a new entity model
-        # Explicitly set external_id to ensure NOT NULL constraint is satisfied (fixes #512)
-        entity = EntityModel(
-            external_id=str(uuid.uuid4()),
-            title=file_name,
-            note_type=note_type,
-            content_type=content_type,
-            file_path=data.file_path,
-            checksum=checksum,
-            created_at=file_metadata.created_at,
-            updated_at=file_metadata.modified_at,
-        )
-        entity = await entity_repository.add(entity)
-
-        # Index the file for search
-        await search_service.index_entity(entity)  # pyright: ignore
-
-        # Return success response
-        return ResourceResponse(
-            entity_id=entity.id,
-            external_id=entity.external_id,
-            file_path=data.file_path,
-            checksum=checksum,
-            size=file_metadata.size,
-            created_at=file_metadata.created_at.timestamp(),
-            modified_at=file_metadata.modified_at.timestamp(),
-        )
-    except HTTPException:
-        # Re-raise HTTP exceptions without wrapping
-        raise
-    except Exception as e:  # pragma: no cover
-        logger.error(f"Error creating resource {data.file_path}: {e}")
-        raise HTTPException(status_code=500, detail=f"Failed to create resource: {str(e)}")
+        except HTTPException:
+            raise
+        except Exception as e:  # pragma: no cover
+            logger.error(f"Error creating resource {data.file_path}: {e}")
+            raise HTTPException(status_code=500, detail=f"Failed to create resource: {str(e)}")
 
 
 @router.put("/{entity_id}", response_model=ResourceResponse)
@@ -211,79 +258,96 @@ async def update_resource(
     Raises:
         HTTPException: 404 if entity not found, 400 for invalid paths
     """
-    try:
-        # Get existing entity by external_id
-        entity = await entity_repository.get_by_external_id(entity_id)
-        if not entity:
-            raise HTTPException(status_code=404, detail=f"Entity {entity_id} not found")
+    with telemetry.operation(
+        "api.request.resource.update",
+        entrypoint="api",
+        domain="resource",
+        action="update",
+    ):
+        try:
+            entity = await entity_repository.get_by_external_id(entity_id)
+            if not entity:
+                raise HTTPException(status_code=404, detail=f"Entity {entity_id} not found")
 
-        # Determine target file path
-        target_file_path = data.file_path if data.file_path else entity.file_path
+            target_file_path = data.file_path if data.file_path else entity.file_path
 
-        # Validate path to prevent path traversal attacks
-        project_path = PathLib(config.home)
-        if not validate_project_path(target_file_path, project_path):
-            logger.warning(
-                f"Invalid file path attempted: {target_file_path} in project {config.name}"
+            project_path = PathLib(config.home)
+            if not validate_project_path(target_file_path, project_path):
+                logger.warning(
+                    f"Invalid file path attempted: {target_file_path} in project {config.name}"
+                )
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Invalid file path: {target_file_path}. "
+                    "Path must be relative and stay within project boundaries.",
+                )
+
+            with telemetry.scope(
+                "api.resource.update.write_file",
+                domain="resource",
+                action="update",
+                phase="write_file",
+            ):
+                if data.file_path and data.file_path != entity.file_path:
+                    await file_service.ensure_directory(PathLib(target_file_path).parent)
+                    if await file_service.exists(entity.file_path):
+                        await file_service.delete_file(entity.file_path)
+                else:
+                    await file_service.ensure_directory(PathLib(target_file_path).parent)
+
+                checksum = await file_service.write_file(target_file_path, data.content)
+
+            with telemetry.scope(
+                "api.resource.update.read_metadata",
+                domain="resource",
+                action="update",
+                phase="read_metadata",
+            ):
+                file_metadata = await file_service.get_file_metadata(target_file_path)
+
+            file_name = PathLib(target_file_path).name
+            content_type = file_service.content_type(target_file_path)
+            note_type = "canvas" if target_file_path.endswith(".canvas") else "file"
+
+            with telemetry.scope(
+                "api.resource.update.update_entity",
+                domain="resource",
+                action="update",
+                phase="update_entity",
+            ):
+                updated_entity = await entity_repository.update(
+                    entity.id,
+                    {
+                        "title": file_name,
+                        "note_type": note_type,
+                        "content_type": content_type,
+                        "file_path": target_file_path,
+                        "checksum": checksum,
+                        "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",
+                domain="resource",
+                action="update",
+                phase="search_index",
+            ):
+                await search_service.index_entity(updated_entity)
+
+            return ResourceResponse(
+                entity_id=entity.id,
+                external_id=entity.external_id,
+                file_path=target_file_path,
+                checksum=checksum,
+                size=file_metadata.size,
+                created_at=file_metadata.created_at.timestamp(),
+                modified_at=file_metadata.modified_at.timestamp(),
             )
-            raise HTTPException(
-                status_code=400,
-                detail=f"Invalid file path: {target_file_path}. "
-                "Path must be relative and stay within project boundaries.",
-            )
-
-        # If moving file, handle the move
-        if data.file_path and data.file_path != entity.file_path:
-            # Ensure new parent directory exists (no-op for S3)
-            await file_service.ensure_directory(PathLib(target_file_path).parent)
-
-            # If old file exists, remove it via file_service (for cloud compatibility)
-            if await file_service.exists(entity.file_path):
-                await file_service.delete_file(entity.file_path)
-        else:
-            # Ensure directory exists for in-place update
-            await file_service.ensure_directory(PathLib(target_file_path).parent)
-
-        # Write content to target file
-        checksum = await file_service.write_file(target_file_path, data.content)
-
-        # Get file info
-        file_metadata = await file_service.get_file_metadata(target_file_path)
-
-        # Determine file details
-        file_name = PathLib(target_file_path).name
-        content_type = file_service.content_type(target_file_path)
-        note_type = "canvas" if target_file_path.endswith(".canvas") else "file"
-
-        # Update entity using internal ID
-        updated_entity = await entity_repository.update(
-            entity.id,
-            {
-                "title": file_name,
-                "note_type": note_type,
-                "content_type": content_type,
-                "file_path": target_file_path,
-                "checksum": checksum,
-                "updated_at": file_metadata.modified_at,
-            },
-        )
-
-        # Index the updated file for search
-        await search_service.index_entity(updated_entity)  # pyright: ignore
-
-        # Return success response
-        return ResourceResponse(
-            entity_id=entity.id,
-            external_id=entity.external_id,
-            file_path=target_file_path,
-            checksum=checksum,
-            size=file_metadata.size,
-            created_at=file_metadata.created_at.timestamp(),
-            modified_at=file_metadata.modified_at.timestamp(),
-        )
-    except HTTPException:
-        # Re-raise HTTP exceptions without wrapping
-        raise
-    except Exception as e:  # pragma: no cover
-        logger.error(f"Error updating resource {entity_id}: {e}")
-        raise HTTPException(status_code=500, detail=f"Failed to update resource: {str(e)}")
+        except HTTPException:
+            raise
+        except Exception as e:  # pragma: no cover
+            logger.error(f"Error updating resource {entity_id}: {e}")
+            raise HTTPException(status_code=500, detail=f"Failed to update resource: {str(e)}")

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

@@ -6,6 +6,7 @@ V1 uses string-based project names which are less efficient and less stable.
 
 from fastapi import APIRouter, HTTPException, Path
 
+from basic_memory import telemetry
 from basic_memory.api.v2.utils import to_search_results
 from basic_memory.repository.semantic_errors import (
     SemanticDependenciesMissingError,
@@ -47,29 +48,73 @@ async def search(
     Returns:
         SearchResponse with paginated search results
     """
-    offset = (page - 1) * page_size
-    # Fetch one extra item to detect whether more pages exist (N+1 trick)
-    fetch_limit = page_size + 1
-    try:
-        results = await search_service.search(query, limit=fetch_limit, offset=offset)
-    except SemanticSearchDisabledError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    except SemanticDependenciesMissingError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-
-    has_more = len(results) > page_size
-    if has_more:
-        results = results[:page_size]
-
-    search_results = await to_search_results(entity_service, results)
-    return SearchResponse(
-        results=search_results,
-        current_page=page,
+    with telemetry.operation(
+        "api.request.search",
+        entrypoint="api",
+        domain="search",
+        action="search",
+        page=page,
         page_size=page_size,
-        has_more=has_more,
-    )
+        retrieval_mode=query.retrieval_mode.value,
+        has_query=bool(
+            (query.text and query.text.strip())
+            or query.title
+            or query.permalink
+            or query.permalink_match
+        ),
+        has_filters=bool(query.note_types or query.entity_types or query.metadata_filters),
+    ):
+        offset = (page - 1) * page_size
+        fetch_limit = page_size + 1
+        try:
+            with telemetry.scope(
+                "api.search.search.execute_query",
+                domain="search",
+                action="search",
+                phase="execute_query",
+                page=page,
+                page_size=page_size,
+            ):
+                results = await search_service.search(query, limit=fetch_limit, offset=offset)
+        except SemanticSearchDisabledError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        except SemanticDependenciesMissingError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+        with telemetry.scope(
+            "api.search.search.paginate_results",
+            domain="search",
+            action="search",
+            phase="paginate_results",
+            result_count=len(results),
+        ):
+            has_more = len(results) > page_size
+            if has_more:
+                results = results[:page_size]
+
+        with telemetry.scope(
+            "api.search.search.hydrate_results",
+            domain="search",
+            action="search",
+            phase="hydrate_results",
+            result_count=len(results),
+        ):
+            search_results = await to_search_results(entity_service, results)
+        with telemetry.scope(
+            "api.search.search.build_response",
+            domain="search",
+            action="search",
+            phase="build_response",
+            result_count=len(search_results),
+        ):
+            return SearchResponse(
+                results=search_results,
+                current_page=page,
+                page_size=page_size,
+                has_more=has_more,
+            )
 
 
 @router.post("/search/reindex")

src/basic_memory/api/v2/utils.py

@@ -1,6 +1,6 @@
-from typing import Optional, List
+from typing import Any, Protocol, Optional, List, Sequence
 
-from basic_memory.repository import EntityRepository
+from basic_memory import telemetry
 from basic_memory.repository.search_repository import SearchIndexRow
 from basic_memory.schemas.memory import (
     EntitySummary,
@@ -11,182 +11,266 @@ 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,
-):
-    # First pass: collect all entity IDs needed for external_id lookup
-    # This includes: entity primary results, observation parent entities, relation from/to entities
-    entity_ids_needed: set[int] = set()
-    for context_item in context_result.results:
-        for item in (
-            [context_item.primary_result] + context_item.observations + context_item.related_results
-        ):
-            if item.type == SearchItemType.ENTITY:
-                # Entity's own ID for its external_id
-                entity_ids_needed.add(item.id)
-            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:
-                # 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.to_id:
-                    entity_ids_needed.add(item.to_id)
-
-    # Batch fetch all entities at once - get both title and external_id
-    entity_title_lookup: dict[int, str] = {}
-    entity_external_id_lookup: dict[int, str] = {}
-    if entity_ids_needed:
-        entities = await entity_repository.find_by_ids(list(entity_ids_needed))
-        for e in entities:
-            entity_title_lookup[e.id] = e.title
-            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:
-            case SearchItemType.ENTITY:
-                return EntitySummary(
-                    external_id=entity_external_id_lookup.get(item.id, ""),
-                    entity_id=item.id,
-                    title=item.title,  # pyright: ignore
-                    permalink=item.permalink,
-                    content=item.content,
-                    file_path=item.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
-                return ObservationSummary(
-                    observation_id=item.id,
-                    entity_id=item.entity_id,  # pyright: ignore
-                    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
-                    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
-                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
-                    from_entity=from_title,
-                    from_entity_id=item.from_id,  # pyright: ignore
-                    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}")
-
-    # Process the hierarchical results
-    hierarchical_results = []
-    for context_item in context_result.results:
-        # Process primary result
-        primary_result = to_summary(context_item.primary_result)
-
-        # Process observations (always ObservationSummary, validated by context_service)
-        observations = [to_summary(obs) for obs in context_item.observations]
-
-        # Process related results
-        related = [to_summary(rel) for rel in context_item.related_results]
-
-        # Add to hierarchical results
-        hierarchical_results.append(
-            ContextResult(
-                primary_result=primary_result,
-                observations=observations,  # pyright: ignore[reportArgumentType]
-                related_results=related,
-            )
-        )
-
-    # Create schema metadata from service metadata
-    metadata = MemoryMetadata(
-        uri=context_result.metadata.uri,
-        types=context_result.metadata.types,
-        depth=context_result.metadata.depth,
-        timeframe=context_result.metadata.timeframe,
-        generated_at=context_result.metadata.generated_at,
-        primary_count=context_result.metadata.primary_count,
-        related_count=context_result.metadata.related_count,
-        total_results=context_result.metadata.primary_count + context_result.metadata.related_count,
-        total_relations=context_result.metadata.total_relations,
-        total_observations=context_result.metadata.total_observations,
-    )
-
-    # Return new GraphContext with just hierarchical results
-    return GraphContext(
-        results=hierarchical_results,
-        metadata=metadata,
+) -> GraphContext:
+    with telemetry.scope(
+        "memory.hydrate_context",
+        domain="memory",
+        action="build_context",
+        phase="hydrate_context",
         page=page,
         page_size=page_size,
-        has_more=context_result.metadata.has_more,
-    )
+        result_count=len(context_result.results),
+    ):
+        # First pass: collect all entity IDs needed for external_id lookup
+        # This includes: entity primary results, observation parent entities, relation from/to entities
+        entity_ids_needed: set[int] = set()
+        for context_item in context_result.results:
+            for item in (
+                [context_item.primary_result]
+                + context_item.observations
+                + context_item.related_results
+            ):
+                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:
+                    # Parent entity ID for entity_external_id
+                    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:
+                        entity_ids_needed.add(item.from_id)
+                    if item.to_id:
+                        entity_ids_needed.add(item.to_id)
 
+        # Batch fetch all entities at once - get both title and external_id
+        entity_title_lookup: dict[int, str] = {}
+        entity_external_id_lookup: dict[int, str] = {}
+        if entity_ids_needed:
+            with telemetry.scope(
+                "memory.hydrate_context.lookup_entities",
+                domain="memory",
+                action="build_context",
+                phase="lookup_entities",
+                result_count=len(entity_ids_needed),
+            ):
+                entities = await entity_repository.find_by_ids(list(entity_ids_needed))
+            for e in entities:
+                entity_title_lookup[e.id] = e.title
+                entity_external_id_lookup[e.id] = e.external_id
 
-async def to_search_results(entity_service: EntityService, results: List[SearchIndexRow]):
-    search_results = []
-    for r in results:
-        entities = await entity_service.get_entities_by_id([r.entity_id, r.from_id, r.to_id])  # pyright: ignore
+        # Helper function to convert items to summaries
+        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=_required_str(item.title, "title"),
+                        permalink=item.permalink,
+                        content=item.content,
+                        file_path=_required_str(item.file_path, "file_path"),
+                        created_at=item.created_at,
+                    )
+                case SearchItemType.OBSERVATION:
+                    entity_ext_id = None
+                    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,
+                        entity_external_id=entity_ext_id,
+                        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
+                    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
+                    )
+                    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,
+                        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,
+                        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,
+                    )
 
-        # Determine which IDs to set based on type
-        entity_id = None
-        observation_id = None
-        relation_id = None
+        with telemetry.scope(
+            "memory.hydrate_context.shape_results",
+            domain="memory",
+            action="build_context",
+            phase="shape_results",
+            result_count=len(context_result.results),
+        ):
+            hierarchical_results = []
+            for context_item in context_result.results:
+                primary_result = to_summary(context_item.primary_result)
+                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,
+                        related_results=related,
+                    )
+                )
 
-        if r.type == SearchItemType.ENTITY:
-            entity_id = r.id
-        elif r.type == SearchItemType.OBSERVATION:
-            observation_id = r.id
-            entity_id = r.entity_id  # Parent entity
-        elif r.type == SearchItemType.RELATION:
-            relation_id = r.id
-            entity_id = r.entity_id  # Parent entity
-
-        search_results.append(
-            SearchResult(
-                title=r.title,  # pyright: ignore
-                type=r.type,  # pyright: ignore
-                permalink=r.permalink,
-                score=r.score,  # pyright: ignore
-                entity=entities[0].permalink if entities else None,
-                content=r.content,
-                matched_chunk=r.matched_chunk_text,
-                file_path=r.file_path,
-                metadata=r.metadata,
-                entity_id=entity_id,
-                observation_id=observation_id,
-                relation_id=relation_id,
-                category=r.category,
-                from_entity=entities[0].permalink if entities else None,
-                to_entity=entities[1].permalink if len(entities) > 1 else None,
-                relation_type=r.relation_type,
-            )
+        metadata = MemoryMetadata(
+            uri=context_result.metadata.uri,
+            types=context_result.metadata.types,
+            depth=context_result.metadata.depth,
+            timeframe=context_result.metadata.timeframe,
+            generated_at=context_result.metadata.generated_at,
+            primary_count=context_result.metadata.primary_count,
+            related_count=context_result.metadata.related_count,
+            total_results=context_result.metadata.primary_count
+            + context_result.metadata.related_count,
+            total_relations=context_result.metadata.total_relations,
+            total_observations=context_result.metadata.total_observations,
         )
-    return search_results
+
+        return GraphContext(
+            results=hierarchical_results,
+            metadata=metadata,
+            page=page,
+            page_size=page_size,
+            has_more=context_result.metadata.has_more,
+        )
+
+
+async def to_search_results(
+    entity_service: EntityServiceBatchLookup, results: List[SearchIndexRow]
+) -> list[SearchResult]:
+    with telemetry.scope(
+        "search.hydrate_results",
+        domain="search",
+        action="search",
+        phase="hydrate_results",
+        result_count=len(results),
+    ):
+        # Collect all unique entity IDs across all results in a single pass
+        # This avoids N+1 queries — one batch fetch instead of one per result
+        all_entity_ids: set[int] = set()
+        for result in results:
+            for eid in (result.entity_id, result.from_id, result.to_id):
+                if eid is not None:
+                    all_entity_ids.add(eid)
+
+        # Single batch fetch for all entities
+        entities_by_id: dict[int, Any] = {}
+        with telemetry.scope(
+            "search.hydrate_results.fetch_entities",
+            domain="search",
+            action="search",
+            phase="fetch_entities",
+            result_count=len(all_entity_ids),
+        ):
+            if all_entity_ids:
+                entities = await entity_service.get_entities_by_id(list(all_entity_ids))
+                entities_by_id = {e.id: e for e in entities}
+
+        search_results = []
+        with telemetry.scope(
+            "search.hydrate_results.shape_results",
+            domain="search",
+            action="search",
+            phase="shape_results",
+            result_count=len(results),
+        ):
+            for result in results:
+                entity_id = None
+                observation_id = None
+                relation_id = None
+
+                if result.type == SearchItemType.ENTITY:
+                    entity_id = result.id
+                elif result.type == SearchItemType.OBSERVATION:
+                    observation_id = result.id
+                    entity_id = result.entity_id
+                elif result.type == SearchItemType.RELATION:
+                    relation_id = result.id
+                    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
+                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=_required_str(result.title, "title"),
+                        type=_search_item_type(result.type),
+                        permalink=result.permalink,
+                        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=_required_str(result.file_path, "file_path"),
+                        metadata=result.metadata,
+                        entity_id=entity_id,
+                        observation_id=observation_id,
+                        relation_id=relation_id,
+                        category=result.category,
+                        from_entity=from_entity.permalink if from_entity else None,
+                        to_entity=to_entity.permalink if to_entity else None,
+                        relation_type=result.relation_type,
+                    )
+                )
+        return search_results

src/basic_memory/cli/app.py

@@ -8,9 +8,11 @@ from typing import Optional  # noqa: E402
 
 import typer  # noqa: E402
 
+from basic_memory.cli.auto_update import maybe_run_periodic_auto_update  # noqa: E402
 from basic_memory.cli.container import CliContainer, set_container  # noqa: E402
 from basic_memory.cli.promo import maybe_show_cloud_promo, maybe_show_init_line  # noqa: E402
 from basic_memory.config import init_cli_logging  # noqa: E402
+from basic_memory import telemetry  # noqa: E402
 
 
 def version_callback(value: bool) -> None:
@@ -41,6 +43,14 @@ def app_callback(
 
     # Initialize logging for CLI (file only, no stdout)
     init_cli_logging()
+    command_name = ctx.invoked_subcommand or "root"
+    ctx.with_resource(
+        telemetry.operation(
+            f"cli.command.{command_name}",
+            entrypoint="cli",
+            command_name=command_name,
+        )
+    )
 
     # --- Composition Root ---
     # Create container and read config (single point of config access)
@@ -52,10 +62,14 @@ def app_callback(
     # Outcome: one-time plain line printed before the subcommand runs.
     maybe_show_init_line(ctx.invoked_subcommand)
 
-    # Trigger: register promo as a post-command callback.
-    # Why: promo output should appear after the command's own output, not before.
-    # Outcome: promo panel renders below the command results (status tree, table, etc.).
-    ctx.call_on_close(lambda: maybe_show_cloud_promo(ctx.invoked_subcommand))
+    # Trigger: register post-command messaging callbacks.
+    # Why: informational/promo/update output belongs below command results.
+    # Outcome: command output remains primary, with optional follow-up notices afterwards.
+    def _post_command_messages() -> None:
+        maybe_show_cloud_promo(ctx.invoked_subcommand)
+        maybe_run_periodic_auto_update(ctx.invoked_subcommand)
+
+    ctx.call_on_close(_post_command_messages)
 
     # Run initialization for commands that don't use the API
     # Skip for 'mcp' command - it has its own lifespan that handles initialization
@@ -70,6 +84,7 @@ def app_callback(
         "tool",
         "reset",
         "reindex",
+        "update",
         "watch",
     }
     if (

src/basic_memory/cli/auto_update.py

@@ -0,0 +1,389 @@
+"""Automatic update checks and upgrades for the Basic Memory CLI."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from enum import Enum
+
+from loguru import logger
+from packaging.version import InvalidVersion, Version
+from rich.console import Console
+
+import basic_memory
+from basic_memory.config import ConfigManager
+
+PACKAGE_NAME = "basic-memory"
+PYPI_JSON_URL = "https://pypi.org/pypi/basic-memory/json"
+
+PYPI_TIMEOUT_SECONDS = 5
+BREW_OUTDATED_TIMEOUT_SECONDS = 60
+UV_UPGRADE_TIMEOUT_SECONDS = 180
+BREW_UPGRADE_TIMEOUT_SECONDS = 600
+
+
+class InstallSource(str, Enum):
+    """How the running CLI appears to have been installed."""
+
+    HOMEBREW = "homebrew"
+    UV_TOOL = "uv_tool"
+    UVX = "uvx"
+    UNKNOWN = "unknown"
+
+
+class AutoUpdateStatus(str, Enum):
+    """Result classification for update checks and installs."""
+
+    SKIPPED = "skipped"
+    UP_TO_DATE = "up_to_date"
+    UPDATE_AVAILABLE = "update_available"
+    UPDATED = "updated"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True)
+class AutoUpdateResult:
+    """Structured result for update checks/install attempts."""
+
+    status: AutoUpdateStatus
+    source: InstallSource
+    checked: bool
+    update_available: bool
+    updated: bool
+    latest_version: str | None = None
+    message: str | None = None
+    error: str | None = None
+    restart_recommended: bool = False
+
+
+def detect_install_source(executable: str | None = None) -> InstallSource:
+    """Infer installation source from the active interpreter path."""
+    active_executable = executable or sys.executable
+    normalized = active_executable.lower().replace("\\", "/")
+
+    if "cellar/basic-memory" in normalized:
+        return InstallSource.HOMEBREW
+    if "uv/tools/basic-memory" in normalized:
+        return InstallSource.UV_TOOL
+    if "/uv/archive-" in normalized:
+        return InstallSource.UVX
+    return InstallSource.UNKNOWN
+
+
+def _is_interactive_session() -> bool:
+    """Return whether stdin/stdout are interactive terminals."""
+    try:
+        return sys.stdin.isatty() and sys.stdout.isatty()
+    except ValueError:
+        # Trigger: stdin/stdout may be closed during transport teardown.
+        # Why: isatty() raises ValueError on closed descriptors.
+        # Outcome: treat as non-interactive and suppress periodic output.
+        return False
+
+
+def _run_subprocess(
+    command: list[str],
+    *,
+    timeout_seconds: int,
+    silent: bool,
+    capture_output: bool,
+) -> subprocess.CompletedProcess[str]:
+    """Run a subprocess with explicit stdio behavior for protocol safety."""
+    # Trigger: silent operation (MCP/background) with no need for subprocess output.
+    # Why: prevent protocol/terminal pollution from child process output.
+    # Outcome: stdout/stderr are discarded unless explicit capture is requested.
+    use_devnull = silent and not capture_output
+    stdout_target = subprocess.DEVNULL if use_devnull else subprocess.PIPE
+    stderr_target = subprocess.DEVNULL if use_devnull else subprocess.PIPE
+
+    return subprocess.run(
+        command,
+        stdin=subprocess.DEVNULL,
+        stdout=stdout_target,
+        stderr=stderr_target,
+        text=True,
+        timeout=timeout_seconds,
+        check=False,
+    )
+
+
+def _version_from_pypi() -> str:
+    """Fetch the latest published package version from PyPI."""
+    request = urllib.request.Request(
+        PYPI_JSON_URL,
+        headers={"User-Agent": f"basic-memory-cli/{basic_memory.__version__}"},
+    )
+    with urllib.request.urlopen(request, timeout=PYPI_TIMEOUT_SECONDS) as response:
+        payload = json.loads(response.read().decode("utf-8"))
+    latest = payload.get("info", {}).get("version")
+    if not latest:
+        raise RuntimeError("PyPI JSON response did not include info.version")
+    return str(latest)
+
+
+def _check_homebrew_update_available(silent: bool) -> tuple[bool, str | None]:
+    """Check whether Homebrew reports an outdated basic-memory formula."""
+    result = _run_subprocess(
+        ["brew", "outdated", "--quiet", PACKAGE_NAME],
+        timeout_seconds=BREW_OUTDATED_TIMEOUT_SECONDS,
+        silent=silent,
+        capture_output=True,
+    )
+    # Trigger: brew outdated exits 1 when the formula IS outdated (with name on stdout).
+    # Why: non-zero exit here means "outdated", not "error".
+    # Outcome: check stdout for the package name to determine outdated status.
+    stdout = (result.stdout or "").strip()
+    is_outdated = PACKAGE_NAME in stdout
+    return is_outdated, None
+
+
+def _check_pypi_update_available() -> tuple[bool, str]:
+    """Compare installed package version with PyPI latest version."""
+    latest = _version_from_pypi()
+    try:
+        current_version = Version(basic_memory.__version__)
+        latest_version = Version(latest)
+    except InvalidVersion as exc:
+        raise RuntimeError(
+            f"Could not compare versions (current={basic_memory.__version__}, latest={latest})"
+        ) from exc
+
+    return latest_version > current_version, latest
+
+
+def _manual_update_hint(source: InstallSource) -> str:
+    """Return manager-appropriate manual update instructions."""
+    if source == InstallSource.UV_TOOL:
+        return "Run `uv tool upgrade basic-memory`."
+    if source == InstallSource.HOMEBREW:
+        return "Run `brew upgrade basic-memory`."
+    return (
+        "Automatic install is not supported for this environment. "
+        "Update with your package manager (for pip: `python3 -m pip install -U basic-memory`)."
+    )
+
+
+def _save_last_checked_timestamp(config_manager: ConfigManager, checked_at: datetime) -> None:
+    """Persist the timestamp for the most recent attempted update check."""
+    config = config_manager.load_config()
+    config.auto_update_last_checked_at = checked_at
+    config_manager.save_config(config)
+
+
+def run_auto_update(
+    *,
+    force: bool = False,
+    check_only: bool = False,
+    silent: bool = False,
+    config_manager: ConfigManager | None = None,
+    now: datetime | None = None,
+    executable: str | None = None,
+) -> AutoUpdateResult:
+    """Run update check/install flow and return a structured result."""
+    manager = config_manager or ConfigManager()
+    config = manager.load_config()
+    source = detect_install_source(executable)
+    checked_at = now or datetime.now()
+
+    if source == InstallSource.UVX:
+        return AutoUpdateResult(
+            status=AutoUpdateStatus.SKIPPED,
+            source=source,
+            checked=False,
+            update_available=False,
+            updated=False,
+            message="uvx runtime detected; updates are managed by uvx cache resolution.",
+        )
+
+    if not force and not config.auto_update:
+        return AutoUpdateResult(
+            status=AutoUpdateStatus.SKIPPED,
+            source=source,
+            checked=False,
+            update_available=False,
+            updated=False,
+            message="Auto-update is disabled in config.",
+        )
+
+    if not force and config.auto_update_last_checked_at is not None:
+        try:
+            elapsed = checked_at - config.auto_update_last_checked_at
+        except TypeError:
+            # Trigger: mixed naive/aware datetimes from manual config edits.
+            # Why: datetime subtraction fails for mixed tz-awareness.
+            # Outcome: ignore the gate once and continue with a forced check path.
+            logger.warning("Auto-update interval gate skipped due to incompatible timestamp format")
+        else:
+            if elapsed < timedelta(seconds=config.update_check_interval):
+                return AutoUpdateResult(
+                    status=AutoUpdateStatus.SKIPPED,
+                    source=source,
+                    checked=False,
+                    update_available=False,
+                    updated=False,
+                    message="Update check interval has not elapsed.",
+                )
+
+    try:
+        # --- Availability check ---
+        latest_version: str | None = None
+        if source == InstallSource.HOMEBREW:
+            update_available, latest_version = _check_homebrew_update_available(silent=silent)
+        else:
+            update_available, latest_version = _check_pypi_update_available()
+
+        if not update_available:
+            return AutoUpdateResult(
+                status=AutoUpdateStatus.UP_TO_DATE,
+                source=source,
+                checked=True,
+                update_available=False,
+                updated=False,
+                latest_version=latest_version,
+                message=f"Basic Memory is up to date ({basic_memory.__version__}).",
+            )
+
+        if check_only:
+            return AutoUpdateResult(
+                status=AutoUpdateStatus.UPDATE_AVAILABLE,
+                source=source,
+                checked=True,
+                update_available=True,
+                updated=False,
+                latest_version=latest_version,
+                message=(
+                    f"Update available (latest: {latest_version or 'unknown'}). "
+                    f"{_manual_update_hint(source)}"
+                ),
+            )
+
+        if source == InstallSource.UNKNOWN:
+            return AutoUpdateResult(
+                status=AutoUpdateStatus.UPDATE_AVAILABLE,
+                source=source,
+                checked=True,
+                update_available=True,
+                updated=False,
+                latest_version=latest_version,
+                message=(
+                    f"Update available (latest: {latest_version or 'unknown'}). "
+                    f"{_manual_update_hint(source)}"
+                ),
+            )
+
+        # --- Automatic install ---
+        command = (
+            ["uv", "tool", "upgrade", PACKAGE_NAME]
+            if source == InstallSource.UV_TOOL
+            else ["brew", "upgrade", PACKAGE_NAME]
+        )
+        timeout = (
+            UV_UPGRADE_TIMEOUT_SECONDS
+            if source == InstallSource.UV_TOOL
+            else BREW_UPGRADE_TIMEOUT_SECONDS
+        )
+
+        install_result = _run_subprocess(
+            command,
+            timeout_seconds=timeout,
+            silent=silent,
+            capture_output=not silent,
+        )
+        if install_result.returncode != 0:
+            stderr = (install_result.stderr or "").strip() if install_result.stderr else ""
+            stdout = (install_result.stdout or "").strip() if install_result.stdout else ""
+            detail = stderr or stdout or "update command failed"
+            return AutoUpdateResult(
+                status=AutoUpdateStatus.FAILED,
+                source=source,
+                checked=True,
+                update_available=True,
+                updated=False,
+                latest_version=latest_version,
+                message="Automatic update failed.",
+                error=detail,
+            )
+
+        return AutoUpdateResult(
+            status=AutoUpdateStatus.UPDATED,
+            source=source,
+            checked=True,
+            update_available=True,
+            updated=True,
+            latest_version=latest_version,
+            message=(
+                "Basic Memory was updated successfully. "
+                "Restart running sessions to use the new version."
+            ),
+            restart_recommended=True,
+        )
+
+    except (
+        RuntimeError,
+        urllib.error.URLError,
+        ValueError,
+        TimeoutError,
+        subprocess.SubprocessError,
+        OSError,
+    ) as exc:
+        logger.warning(f"Auto-update check failed: {exc}")
+        return AutoUpdateResult(
+            status=AutoUpdateStatus.FAILED,
+            source=source,
+            checked=True,
+            update_available=False,
+            updated=False,
+            message="Automatic update check failed.",
+            error=str(exc),
+        )
+    finally:
+        # Trigger: we attempted a check path (including failures).
+        # Why: repeated failing checks on every command create noise and unnecessary network load.
+        # Outcome: next periodic check is gated by update_check_interval.
+        try:
+            _save_last_checked_timestamp(manager, checked_at)
+        except Exception as exc:  # pragma: no cover
+            logger.warning(f"Failed to persist auto-update timestamp: {exc}")
+
+
+def maybe_run_periodic_auto_update(
+    invoked_subcommand: str | None,
+    *,
+    config_manager: ConfigManager | None = None,
+    is_interactive: bool | None = None,
+    console: Console | None = None,
+) -> AutoUpdateResult | None:
+    """Run a periodic auto-update check for interactive CLI sessions."""
+    interactive = _is_interactive_session() if is_interactive is None else is_interactive
+    if not interactive:
+        return None
+    if invoked_subcommand in {None, "mcp", "update"}:
+        return None
+
+    result = run_auto_update(
+        force=False,
+        check_only=False,
+        silent=False,
+        config_manager=config_manager,
+    )
+
+    if result.status in {
+        AutoUpdateStatus.UPDATE_AVAILABLE,
+        AutoUpdateStatus.UPDATED,
+        AutoUpdateStatus.FAILED,
+    }:
+        out = console or Console()
+        if result.status == AutoUpdateStatus.UPDATED:
+            out.print(f"[green]{result.message}[/green]")
+        elif result.status == AutoUpdateStatus.FAILED:
+            error_detail = f" {result.error}" if result.error else ""
+            out.print(f"[yellow]{result.message}{error_detail}[/yellow]")
+        elif result.message:
+            out.print(f"[cyan]{result.message}[/cyan]")
+
+    return result

src/basic_memory/cli/commands/__init__.py

@@ -8,6 +8,7 @@ from . import (
     project,
     format,
     schema,
+    update,
 )
 
 __all__ = [
@@ -23,4 +24,5 @@ __all__ = [
     "project",
     "format",
     "schema",
+    "update",
 ]

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

@@ -45,14 +45,26 @@ def get_cloud_config() -> tuple[str, str, str]:
 
 async def get_authenticated_headers(auth: CLIAuth | None = None) -> dict[str, str]:
     """
-    Get authentication headers with JWT token.
-    handles jwt refresh if needed.
+    Get authentication headers for cloud API requests.
+
+    Credential priority mirrors async_client._resolve_cloud_token():
+      1. API key (config.cloud_api_key) — fast, no refresh needed
+      2. OAuth token via CLIAuth — handles JWT refresh automatically
     """
+    # --- API key (preferred) ---
+    config_manager = ConfigManager()
+    api_key = config_manager.config.cloud_api_key
+    if api_key:
+        return {"Authorization": f"Bearer {api_key}"}
+
+    # --- OAuth fallback ---
     client_id, domain, _ = get_cloud_config()
     auth_obj = auth or CLIAuth(client_id=client_id, authkit_domain=domain)
     token = await auth_obj.get_valid_token()
     if not token:
-        console.print("[red]Not authenticated. Please run 'bm cloud login' first.[/red]")
+        console.print(
+            "[red]Not authenticated. Run 'bm cloud set-key <key>' or 'bm cloud login' first.[/red]"
+        )
         raise typer.Exit(1)
 
     return {"Authorization": f"Bearer {token}"}
@@ -87,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

@@ -2,10 +2,12 @@
 
 from basic_memory.cli.commands.cloud.api_client import make_api_request
 from basic_memory.config import ConfigManager
+from basic_memory.mcp.async_client import resolve_configured_workspace
 from basic_memory.schemas.cloud import (
     CloudProjectList,
     CloudProjectCreateRequest,
     CloudProjectCreateResponse,
+    ProjectVisibility,
 )
 from basic_memory.utils import generate_permalink
 
@@ -16,12 +18,33 @@ class CloudUtilsError(Exception):
     pass
 
 
+def _workspace_headers(
+    *,
+    project_name: str | None = None,
+    workspace: str | None = None,
+) -> dict[str, str]:
+    """Build optional workspace headers using the CLI config resolution chain."""
+    resolved_workspace = resolve_configured_workspace(
+        project_name=project_name,
+        workspace=workspace,
+    )
+    if resolved_workspace is None:
+        return {}
+    return {"X-Workspace-ID": resolved_workspace}
+
+
 async def fetch_cloud_projects(
     *,
+    project_name: str | None = None,
+    workspace: str | None = None,
     api_request=make_api_request,
 ) -> 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
     """
@@ -30,7 +53,11 @@ async def fetch_cloud_projects(
         config = config_manager.config
         host_url = config.cloud_host.rstrip("/")
 
-        response = await api_request(method="GET", url=f"{host_url}/proxy/v2/projects/")
+        response = await api_request(
+            method="GET",
+            url=f"{host_url}/proxy/v2/projects/",
+            headers=_workspace_headers(project_name=project_name, workspace=workspace),
+        )
 
         return CloudProjectList.model_validate(response.json())
     except Exception as e:
@@ -40,12 +67,16 @@ async def fetch_cloud_projects(
 async def create_cloud_project(
     project_name: str,
     *,
+    workspace: str | None = None,
+    visibility: ProjectVisibility = "workspace",
     api_request=make_api_request,
 ) -> CloudProjectCreateResponse:
     """Create a new project on cloud.
 
     Args:
         project_name: Name of project to create
+        workspace: Optional workspace override for tenant-scoped project creation
+        visibility: Visibility for the created cloud project
 
     Returns:
         CloudProjectCreateResponse with project details from API
@@ -62,12 +93,16 @@ async def create_cloud_project(
             name=project_name,
             path=project_path,
             set_default=False,
+            visibility=visibility,
         )
 
         response = await api_request(
             method="POST",
             url=f"{host_url}/proxy/v2/projects/",
-            headers={"Content-Type": "application/json"},
+            headers={
+                "Content-Type": "application/json",
+                **_workspace_headers(project_name=project_name, workspace=workspace),
+            },
             json_data=project_data.model_dump(),
         )
 
@@ -81,28 +116,38 @@ 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
 
 
-async def project_exists(project_name: str, *, api_request=make_api_request) -> bool:
+async def project_exists(
+    project_name: str,
+    *,
+    workspace: str | None = None,
+    api_request=make_api_request,
+) -> bool:
     """Check if a project exists on cloud.
 
     Args:
         project_name: Name of project to check
+        workspace: Optional workspace override for tenant-scoped project lookup
 
     Returns:
         True if project exists, False otherwise
+
+    Raises:
+        CloudUtilsError: If the project list cannot be fetched from cloud
     """
-    try:
-        projects = await fetch_cloud_projects(api_request=api_request)
-        project_names = {p.name for p in projects.projects}
-        return project_name in project_names
-    except Exception:
-        return False
+    projects = await fetch_cloud_projects(
+        project_name=project_name,
+        workspace=workspace,
+        api_request=api_request,
+    )
+    project_names = {p.name for p in projects.projects}
+    return project_name in project_names

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

@@ -54,7 +54,7 @@ def _require_cloud_credentials(config) -> None:
 
 async def _get_cloud_project(name: str) -> ProjectItem | None:
     """Fetch a project by name from the cloud API."""
-    async with get_client() as client:
+    async with get_client(project_name=name) as client:
         projects_list = await ProjectClient(client).list_projects()
         for proj in projects_list.projects:
             if generate_permalink(proj.name) == generate_permalink(name):
@@ -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() as client:
-                        return await ProjectClient(client).sync(
-                            project_data.external_id, force_full=True
-                        )
-
-                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)
@@ -195,26 +179,13 @@ def bisync_project_command(
             # Update config — sync_entry is guaranteed non-None because
             # _get_sync_project validated local_sync_path (which comes from sync_entry)
             sync_entry = config.projects.get(name)
-            assert sync_entry is not None
+            if sync_entry is None:
+                raise RuntimeError(
+                    f"Sync entry for project '{name}' unexpectedly missing after validation"
+                )
             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() as client:
-                        return await ProjectClient(client).sync(
-                            project_data.external_id, force_full=True
-                        )
-
-                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)
@@ -320,7 +291,7 @@ def setup_project_sync(
 
     async def _verify_project_exists():
         """Verify the project exists on cloud by listing all projects."""
-        async with get_client() as client:
+        async with get_client(project_name=name) as client:
             projects_list = await ProjectClient(client).list_projects()
             project_names = [p.name for p in projects_list.projects]
             if name not in project_names:

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

@@ -1,5 +1,6 @@
 """Upload CLI commands for basic-memory projects."""
 
+from functools import partial
 from pathlib import Path
 
 import typer
@@ -8,12 +9,16 @@ from rich.console import Console
 from basic_memory.cli.app import cloud_app
 from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.cli.commands.cloud.cloud_utils import (
+    CloudUtilsError,
     create_cloud_project,
     project_exists,
     sync_project,
 )
 from basic_memory.cli.commands.cloud.upload import upload_path
-from basic_memory.mcp.async_client import get_cloud_control_plane_client
+from basic_memory.mcp.async_client import (
+    get_cloud_control_plane_client,
+    resolve_configured_workspace,
+)
 
 console = Console()
 
@@ -73,12 +78,20 @@ def upload(
     """
 
     async def _upload():
+        resolved_workspace = resolve_configured_workspace(project_name=project)
+
+        try:
+            project_already_exists = await project_exists(project, workspace=resolved_workspace)
+        except CloudUtilsError as e:
+            console.print(f"[red]Failed to check cloud project '{project}': {e}[/red]")
+            raise typer.Exit(1)
+
         # Check if project exists
-        if not await project_exists(project):
+        if not project_already_exists:
             if create_project:
                 console.print(f"[blue]Creating cloud project '{project}'...[/blue]")
                 try:
-                    await create_cloud_project(project)
+                    await create_cloud_project(project, workspace=resolved_workspace)
                     console.print(f"[green]Created project '{project}'[/green]")
                 except Exception as e:
                     console.print(f"[red]Failed to create project: {e}[/red]")
@@ -93,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]"
@@ -106,7 +121,10 @@ def upload(
             verbose=verbose,
             use_gitignore=not no_gitignore,
             dry_run=dry_run,
-            client_cm_factory=get_cloud_control_plane_client,
+            client_cm_factory=partial(
+                get_cloud_control_plane_client,
+                workspace=resolved_workspace,
+            ),
         )
         if not success:
             console.print("[red]Upload failed[/red]")
@@ -117,12 +135,14 @@ def upload(
         else:
             console.print(f"[green]Successfully uploaded to '{project}'[/green]")
 
-        # Sync project if requested (skip on dry run)
-        # Force full scan after bisync to ensure database is up-to-date with synced files
+        # Sync project if requested (skip on dry run).
+        # Trigger: upload adds new files the watcher has not observed locally.
+        # Why: force_full ensures those freshly uploaded files are indexed immediately.
+        # Outcome: upload keeps its eager reindex while sync/bisync stay incremental.
         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

@@ -54,6 +54,9 @@ async def run_doctor() -> None:
                 if not status.new_project:
                     raise ValueError("Failed to create doctor project")
                 project_id = status.new_project.external_id
+                # Use the resolved path from the server — when project_root is configured,
+                # the actual project directory differs from the requested temp_path
+                project_path = Path(status.new_project.path)
                 console.print(f"[green]OK[/green] Created doctor project: {project_name}")
 
                 # --- DB -> File: create an entity via API ---
@@ -68,7 +71,7 @@ async def run_doctor() -> None:
                 )
                 api_result = await knowledge_client.create_entity(api_note.model_dump(), fast=False)
 
-                api_file = temp_path / api_result.file_path
+                api_file = project_path / api_result.file_path
                 if not api_file.exists():
                     raise ValueError(f"API note file missing: {api_result.file_path}")
 
@@ -79,7 +82,7 @@ async def run_doctor() -> None:
                 console.print("[green]OK[/green] API write created file")
 
                 # --- File -> DB: write markdown file directly, then sync ---
-                parser = EntityParser(temp_path)
+                parser = EntityParser(project_path)
                 processor = MarkdownProcessor(parser)
                 manual_markdown = EntityMarkdown(
                     frontmatter=EntityFrontmatter(
@@ -93,12 +96,12 @@ async def run_doctor() -> None:
                     content=f"# {manual_note_title}\n\n- [note] File to DB check",
                 )
 
-                manual_path = temp_path / "doctor" / "manual-note.md"
+                manual_path = project_path / "doctor" / "manual-note.md"
                 await processor.write_file(manual_path, manual_markdown)
                 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/mcp.py

@@ -1,12 +1,14 @@
 """MCP server command with streamable HTTP transport."""
 
 import os
+import threading
 from typing import Any, Optional
 
 import typer
 from loguru import logger
 
 from basic_memory.cli.app import app
+from basic_memory.cli.auto_update import AutoUpdateStatus, run_auto_update
 from basic_memory.config import ConfigManager, init_mcp_logging
 
 
@@ -80,6 +82,22 @@ def mcp(
         os.environ["BASIC_MEMORY_MCP_PROJECT"] = project_name
         logger.info(f"MCP server constrained to project: {project_name}")
 
+    def _run_background_auto_update() -> None:
+        result = run_auto_update(force=False, check_only=False, silent=True)
+        if result.restart_recommended:
+            logger.info(
+                "A newer Basic Memory version was installed and will apply on next restart."
+            )
+        elif result.status == AutoUpdateStatus.FAILED and result.error:
+            logger.warning(f"MCP background auto-update failed: {result.error}")
+
+    # Trigger: stdio transport corresponds to local user installs.
+    # Why: server transports (HTTP/SSE) run in managed environments where
+    # package-manager self-upgrades are inappropriate.
+    # Outcome: background auto-update runs only for local stdio MCP sessions.
+    if transport == "stdio":
+        threading.Thread(target=_run_background_auto_update, daemon=True).start()
+
     # Run the MCP server (blocks)
     # Lifespan handles: initialization, migrations, file sync, cleanup
     logger.info(f"Starting MCP server with {transport.upper()} transport")

src/basic_memory/cli/commands/project.py

@@ -4,6 +4,7 @@ import json
 import os
 from datetime import datetime
 from pathlib import Path
+from typing import cast
 
 import typer
 from rich.console import Console, Group
@@ -13,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,
@@ -25,8 +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 (
+    CloudProjectIndexStatus,
+    CloudTenantIndexStatusResponse,
+    ProjectVisibility,
+)
 from basic_memory.schemas.project_info import ProjectItem, ProjectList
 from basic_memory.utils import generate_permalink, normalize_project_path
 
@@ -56,6 +63,262 @@ 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:
+        return "workspace"
+
+    normalized = visibility.strip().lower()
+    if normalized in {"workspace", "shared", "private"}:
+        return cast(ProjectVisibility, normalized)
+
+    raise ValueError("Invalid visibility. Expected one of: workspace, shared, private.")
+
+
+def _resolve_workspace_id(config, workspace: str | None) -> str | None:
+    """Resolve a workspace name or tenant_id to a tenant_id."""
+    from basic_memory.mcp.project_context import (
+        _workspace_choices,
+        _workspace_matches_identifier,
+        get_available_workspaces,
+    )
+
+    if workspace is not None:
+        workspaces = run_with_cleanup(get_available_workspaces())
+        matches = [ws for ws in workspaces if _workspace_matches_identifier(ws, workspace)]
+        if not matches:
+            console.print(f"[red]Error: Workspace '{workspace}' not found[/red]")
+            if workspaces:
+                console.print(f"[dim]Available:\n{_workspace_choices(workspaces)}[/dim]")
+            raise typer.Exit(1)
+        if len(matches) > 1:
+            console.print(
+                f"[red]Error: Workspace name '{workspace}' matches multiple workspaces. "
+                f"Use tenant_id instead.[/red]"
+            )
+            console.print(f"[dim]Available:\n{_workspace_choices(workspaces)}[/dim]")
+            raise typer.Exit(1)
+        return matches[0].tenant_id
+
+    if config.default_workspace:
+        return config.default_workspace
+
+    try:
+        workspaces = run_with_cleanup(get_available_workspaces())
+        if len(workspaces) == 1:
+            return workspaces[0].tenant_id
+    except Exception:
+        # Workspace resolution is optional until a command needs a specific tenant.
+        pass
+
+    return None
+
+
 @project_app.command("list")
 def list_projects(
     local: bool = typer.Option(False, "--local", help="Force local routing for this command"),
@@ -128,7 +391,7 @@ def list_projects(
         table.add_column("Cloud Path", style="green")
         table.add_column("Workspace", style="green")
         table.add_column("CLI Route", style="blue")
-        table.add_column("MCP (stdio)", style="blue")
+        table.add_column("MCP", style="blue")
         table.add_column("Sync", style="green")
         table.add_column("Default", style="magenta")
 
@@ -164,6 +427,11 @@ def list_projects(
             elif entry and entry.mode == ProjectMode.LOCAL and entry.path:
                 local_path = format_path(normalize_project_path(entry.path))
 
+            # Clear local path for cloud-mode projects — only local projects
+            # should display a local path
+            if entry and entry.mode == ProjectMode.CLOUD:
+                local_path = ""
+
             cloud_path = ""
             if cloud_project is not None:
                 cloud_path = normalize_project_path(cloud_project.path)
@@ -182,23 +450,37 @@ def list_projects(
             is_default = config.default_project == project_name
 
             has_sync = bool(entry and entry.local_sync_path)
-            mcp_stdio_target = "local" if local_project is not None else "n/a"
+            # Determine MCP transport based on project routing mode
+            if entry and entry.mode == ProjectMode.CLOUD:
+                mcp_transport = "https"
+            elif entry is None and cloud_project is not None:
+                mcp_transport = "https"
+            else:
+                mcp_transport = "stdio"
 
             # Show workspace name (type) for cloud-sourced projects
             ws_label = ""
             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,
                 "local_path": local_path,
                 "cloud_path": cloud_path,
                 "cli_route": cli_route,
-                "mcp_stdio": mcp_stdio_target,
+                "mcp_stdio": mcp_transport,
                 "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:
@@ -214,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", "")
@@ -246,6 +528,16 @@ def add_project(
     local_path: str = typer.Option(
         None, "--local-path", help="Local sync path for cloud mode (optional)"
     ),
+    workspace: str = typer.Option(
+        None,
+        "--workspace",
+        help="Cloud workspace name or tenant_id (cloud mode only)",
+    ),
+    visibility: str = typer.Option(
+        None,
+        "--visibility",
+        help="Cloud project visibility: workspace, shared, or private",
+    ),
     set_default: bool = typer.Option(False, "--default", help="Set as default project"),
     local: bool = typer.Option(
         False, "--local", help="Force local API routing (ignore cloud mode)"
@@ -260,6 +552,8 @@ def add_project(
     Cloud mode examples:\n
         bm project add research                           # No local sync\n
         bm project add research --local-path ~/docs       # With local sync\n
+        bm project add research --cloud --visibility shared\n
+        bm project add research --cloud --workspace Personal --visibility shared\n
 
     Local mode example:\n
         bm project add research ~/Documents/research
@@ -274,6 +568,7 @@ def add_project(
 
     # Determine effective mode: default local, cloud only when explicitly requested.
     effective_cloud_mode = cloud and not local
+    resolved_workspace_id: str | None = None
 
     # Resolve local sync path early (needed for both cloud and local mode)
     local_sync_path: str | None = None
@@ -282,18 +577,31 @@ def add_project(
 
     if effective_cloud_mode:
         _require_cloud_credentials(config)
+        try:
+            resolved_visibility = _normalize_project_visibility(visibility)
+        except ValueError as e:
+            console.print(f"[red]Error: {e}[/red]")
+            raise typer.Exit(1)
+        resolved_workspace_id = _resolve_workspace_id(config, workspace)
         # Cloud mode: path auto-generated from name, local sync is optional
 
         async def _add_project():
-            async with get_client() as client:
+            async with get_client(workspace=resolved_workspace_id) as client:
                 data = {
                     "name": name,
                     "path": generate_permalink(name),
                     "local_sync_path": local_sync_path,
                     "set_default": set_default,
+                    "visibility": resolved_visibility,
                 }
                 return await ProjectClient(client).create_project(data)
     else:
+        if workspace is not None:
+            console.print("[red]Error: --workspace is only supported in cloud mode[/red]")
+            raise typer.Exit(1)
+        if visibility is not None:
+            console.print("[red]Error: --visibility is only supported in cloud mode[/red]")
+            raise typer.Exit(1)
         # Local mode: path is required
         if path is None:
             console.print("[red]Error: path argument is required in local mode[/red]")
@@ -312,25 +620,34 @@ def add_project(
             result = run_with_cleanup(_add_project())
         console.print(f"[green]{result.message}[/green]")
 
+        # Trigger: local config needs enough metadata to route future commands back to cloud.
+        # Why: explicit workspace selection and local sync state should persist across CLI sessions.
+        # Outcome: cloud-backed projects keep cloud mode, workspace_id, and optional local sync path.
+        if effective_cloud_mode and (local_sync_path or resolved_workspace_id):
+            entry = config.projects.get(name)
+            if entry:
+                entry.mode = ProjectMode.CLOUD
+                if local_sync_path:
+                    entry.path = local_sync_path
+                    entry.local_sync_path = local_sync_path
+                if resolved_workspace_id:
+                    entry.workspace_id = resolved_workspace_id
+            else:
+                # Project may not be in local config yet (cloud-only add)
+                config.projects[name] = ProjectEntry(
+                    path=local_sync_path or "",
+                    mode=ProjectMode.CLOUD,
+                    local_sync_path=local_sync_path,
+                    workspace_id=resolved_workspace_id,
+                )
+            ConfigManager().save_config(config)
+
         # Save local sync path to config if in cloud mode
         if effective_cloud_mode and local_sync_path:
             # Create local directory if it doesn't exist
             local_dir = Path(local_sync_path)
             local_dir.mkdir(parents=True, exist_ok=True)
 
-            # Update project entry — path is always the local directory
-            entry = config.projects.get(name)
-            if entry:
-                entry.path = local_sync_path
-                entry.local_sync_path = local_sync_path
-            else:
-                # Project may not be in local config yet (cloud-only add)
-                config.projects[name] = ProjectEntry(
-                    path=local_sync_path,
-                    local_sync_path=local_sync_path,
-                )
-            ConfigManager().save_config(config)
-
             console.print(f"\n[green]Local sync path configured: {local_sync_path}[/green]")
             console.print("\nNext steps:")
             console.print(f"  1. Preview: bm cloud bisync --name {name} --resync --dry-run")
@@ -564,45 +881,7 @@ def set_cloud(
         console.print("[dim]Run 'bm cloud api-key save <key>' or 'bm cloud login' first[/dim]")
         raise typer.Exit(1)
 
-    # --- Resolve workspace to tenant_id ---
-    resolved_workspace_id: str | None = None
-
-    if workspace is not None:
-        # Explicit --workspace: resolve to tenant_id via cloud lookup
-        from basic_memory.mcp.project_context import (
-            get_available_workspaces,
-            _workspace_matches_identifier,
-            _workspace_choices,
-        )
-
-        workspaces = run_with_cleanup(get_available_workspaces())
-        matches = [ws for ws in workspaces if _workspace_matches_identifier(ws, workspace)]
-        if not matches:
-            console.print(f"[red]Error: Workspace '{workspace}' not found[/red]")
-            if workspaces:
-                console.print(f"[dim]Available:\n{_workspace_choices(workspaces)}[/dim]")
-            raise typer.Exit(1)
-        if len(matches) > 1:
-            console.print(
-                f"[red]Error: Workspace name '{workspace}' matches multiple workspaces. "
-                f"Use tenant_id instead.[/red]"
-            )
-            console.print(f"[dim]Available:\n{_workspace_choices(workspaces)}[/dim]")
-            raise typer.Exit(1)
-        resolved_workspace_id = matches[0].tenant_id
-    elif config.default_workspace:
-        # Fall back to global default
-        resolved_workspace_id = config.default_workspace
-    else:
-        # Try auto-select if single workspace
-        try:
-            from basic_memory.mcp.project_context import get_available_workspaces
-
-            workspaces = run_with_cleanup(get_available_workspaces())
-            if len(workspaces) == 1:
-                resolved_workspace_id = workspaces[0].tenant_id
-        except Exception:
-            pass  # Workspace resolution is optional at set-cloud time
+    resolved_workspace_id = _resolve_workspace_id(config, workspace)
 
     config.set_project_mode(name, ProjectMode.CLOUD)
     if resolved_workspace_id:
@@ -787,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))
@@ -847,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:
@@ -885,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/cli/commands/update.py

@@ -0,0 +1,40 @@
+"""Manual update command for Basic Memory CLI."""
+
+import typer
+from rich.console import Console
+
+from basic_memory.cli.app import app
+from basic_memory.cli.auto_update import AutoUpdateStatus, run_auto_update
+
+console = Console()
+
+
+@app.command("update")
+def update(
+    check: bool = typer.Option(
+        False,
+        "--check",
+        help="Check for updates only (do not install).",
+    ),
+) -> None:
+    """Check for updates and install when supported."""
+    result = run_auto_update(force=True, check_only=check, silent=False)
+
+    if result.status == AutoUpdateStatus.FAILED:
+        detail = f" {result.error}" if result.error else ""
+        console.print(f"[red]{result.message or 'Update failed.'}{detail}[/red]")
+        raise typer.Exit(1)
+
+    if result.status == AutoUpdateStatus.UPDATED:
+        console.print(f"[green]{result.message or 'Basic Memory updated successfully.'}[/green]")
+        return
+
+    if result.status == AutoUpdateStatus.UP_TO_DATE:
+        console.print(f"[green]{result.message or 'Basic Memory is up to date.'}[/green]")
+        return
+
+    if result.status == AutoUpdateStatus.UPDATE_AVAILABLE:
+        console.print(f"[cyan]{result.message or 'Update available.'}[/cyan]")
+        return
+
+    console.print(f"[dim]{result.message or 'No update action was performed.'}[/dim]")

src/basic_memory/cli/main.py

@@ -28,6 +28,7 @@ if not _version_only_invocation(sys.argv[1:]):
         schema,
         status,
         tool,
+        update,
     )
 
 warnings.filterwarnings("ignore")  # pragma: no cover

src/basic_memory/cli/promo.py

@@ -12,7 +12,7 @@ from basic_memory.config import ConfigManager
 
 OSS_DISCOUNT_CODE = "BMFOSS"
 CLOUD_LEARN_MORE_URL = (
-    "https://basicmemory.com?utm_source=bm-cli&utm_medium=promo&utm_campaign=cloud-upsell"
+    "https://basicmemory.com?utm_source=bm-foss&utm_medium=promo&utm_campaign=cloud-upsell"
 )
 
 

src/basic_memory/config.py

@@ -6,14 +6,16 @@ import os
 import shutil
 from dataclasses import dataclass
 from datetime import datetime
-from pathlib import Path
-from typing import Any, Dict, Literal, Optional, List, Tuple
 from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, Literal, Optional, List, Tuple
 
 from loguru import logger
 from pydantic import AliasChoices, BaseModel, Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+from basic_memory import __version__
+from basic_memory.telemetry import configure_telemetry
 from basic_memory.utils import setup_logging, generate_permalink
 
 
@@ -48,6 +50,23 @@ def _default_semantic_search_enabled() -> bool:
     )
 
 
+def _default_fastembed_cache_dir() -> str:
+    """Default FastEmbed model cache to ~/.basic-memory/fastembed_cache.
+
+    FastEmbed's own default is <system-temp>/fastembed_cache (e.g. /tmp/fastembed_cache on
+    Linux), which is ephemeral in sandboxed runtimes like Codex CLI and can disappear between
+    invocations, causing ONNXRuntimeError: NO_SUCHFILE on every subsequent run.
+
+    By defaulting to a path inside the Basic Memory data directory we stay consistent with
+    where other app state lives and ensure the ONNX model survives across sessions.
+    Honors BASIC_MEMORY_CONFIG_DIR so isolated test environments remain self-contained.
+    """
+    if config_dir := os.getenv("BASIC_MEMORY_CONFIG_DIR"):
+        return str(Path(config_dir) / "fastembed_cache")
+    home = os.getenv("HOME", str(Path.home()))
+    return str(Path(home) / DATA_DIR_NAME / "fastembed_cache")
+
+
 @dataclass
 class ProjectConfig:
     """Configuration for a specific basic-memory project."""
@@ -120,6 +139,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(
@@ -140,6 +164,24 @@ class BasicMemoryConfig(BaseSettings):
     # overridden by ~/.basic-memory/config.json
     log_level: str = "INFO"
 
+    # Optional Logfire telemetry (disabled by default)
+    logfire_enabled: bool = Field(
+        default=False,
+        description="Enable Logfire instrumentation for local development or managed deployments.",
+    )
+    logfire_send_to_logfire: bool = Field(
+        default=False,
+        description="When true, allow Logfire to export telemetry to the configured backend.",
+    )
+    logfire_service_name: str = Field(
+        default="basic-memory",
+        description="Base service name used when constructing entrypoint-specific Logfire service names.",
+    )
+    logfire_environment: str | None = Field(
+        default=None,
+        description="Optional override for Logfire environment. Defaults to env when unset.",
+    )
+
     # Database configuration
     database_backend: DatabaseBackend = Field(
         default=DatabaseBackend.SQLITE,
@@ -168,19 +210,39 @@ 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.",
+        default_factory=_default_fastembed_cache_dir,
+        description="Cache directory for FastEmbed model artifacts. Defaults to "
+        "~/.basic-memory/fastembed_cache to avoid FastEmbed's ephemeral /tmp default, "
+        "which breaks MCP in sandboxed runtimes (e.g. Codex CLI). "
+        "Set to null to use FastEmbed's own default.",
     )
     semantic_embedding_threads: int | None = Field(
         default=None,
@@ -203,6 +265,12 @@ class BasicMemoryConfig(BaseSettings):
         ge=0.0,
         le=1.0,
     )
+    default_search_type: Literal["text", "vector", "hybrid"] | None = Field(
+        default=None,
+        description="Default search type for search_notes when not specified per-query. "
+        "Valid values: text, vector, hybrid. "
+        "When unset, defaults to 'hybrid' if semantic search is enabled, otherwise 'text'.",
+    )
 
     # Database connection pool configuration (Postgres only)
     db_pool_size: int = Field(
@@ -254,6 +322,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,
@@ -351,6 +444,22 @@ class BasicMemoryConfig(BaseSettings):
         description="Most recent cloud promo version shown in CLI.",
     )
 
+    auto_update: bool = Field(
+        default=True,
+        description="Enable automatic CLI update checks and installs when supported.",
+    )
+
+    update_check_interval: int = Field(
+        default=86400,
+        description="Seconds between automatic update checks.",
+        gt=0,
+    )
+
+    auto_update_last_checked_at: Optional[datetime] = Field(
+        default=None,
+        description="Timestamp of the last attempted automatic update check.",
+    )
+
     cloud_api_key: Optional[str] = Field(
         default=None,
         description="API key for cloud access (bmc_ prefixed). Account-level, not per-project.",
@@ -629,6 +738,12 @@ class BasicMemoryConfig(BaseSettings):
 
 # Module-level cache for configuration
 _CONFIG_CACHE: Optional[BasicMemoryConfig] = None
+# Track config file mtime+size so cross-process changes (e.g. `bm project set-cloud`
+# in a separate terminal) invalidate the cache in long-lived processes like the
+# MCP stdio server. Using both mtime and size guards against coarse-granularity
+# filesystems where two writes within the same second share the same mtime.
+_CONFIG_MTIME: Optional[float] = None
+_CONFIG_SIZE: Optional[int] = None
 
 
 class ConfigManager:
@@ -662,13 +777,38 @@ class ConfigManager:
         Environment variables take precedence over file config values,
         following Pydantic Settings best practices.
 
-        Uses module-level cache for performance across ConfigManager instances.
+        Uses module-level cache with file mtime validation so that
+        cross-process config changes (e.g. `bm project set-cloud` in a
+        separate terminal) are picked up by long-lived processes like
+        the MCP stdio server.
         """
-        global _CONFIG_CACHE
+        global _CONFIG_CACHE, _CONFIG_MTIME, _CONFIG_SIZE
 
-        # Return cached config if available
+        # Trigger: cached config exists but the on-disk file may have been
+        # modified by another process (CLI command in a different terminal).
+        # Why: the MCP server is long-lived; without this check it would
+        # serve stale project routing forever.
+        # Outcome: cheap os.stat() per access; re-read only when mtime or size differs.
         if _CONFIG_CACHE is not None:
-            return _CONFIG_CACHE
+            try:
+                st = self.config_file.stat()
+                current_mtime = st.st_mtime
+                current_size = st.st_size
+            except OSError:
+                current_mtime = None
+                current_size = None
+
+            if (
+                current_mtime is not None
+                and current_mtime == _CONFIG_MTIME
+                and current_size == _CONFIG_SIZE
+            ):
+                return _CONFIG_CACHE
+
+            # mtime/size changed or file gone — invalidate and fall through to re-read
+            _CONFIG_CACHE = None
+            _CONFIG_MTIME = None
+            _CONFIG_SIZE = None
 
         if self.config_file.exists():
             try:
@@ -723,6 +863,15 @@ class ConfigManager:
 
                 _CONFIG_CACHE = BasicMemoryConfig(**merged_data)
 
+                # Record mtime+size so subsequent calls detect cross-process changes
+                try:
+                    st = self.config_file.stat()
+                    _CONFIG_MTIME = st.st_mtime
+                    _CONFIG_SIZE = st.st_size
+                except OSError:
+                    _CONFIG_MTIME = None
+                    _CONFIG_SIZE = None
+
                 # Re-save to normalize legacy config into current format
                 if needs_resave:
                     # Create backup before overwriting so users can revert if needed
@@ -753,10 +902,12 @@ class ConfigManager:
 
     def save_config(self, config: BasicMemoryConfig) -> None:
         """Save configuration to file and invalidate cache."""
-        global _CONFIG_CACHE
+        global _CONFIG_CACHE, _CONFIG_MTIME, _CONFIG_SIZE
         save_basic_memory_config(self.config_file, config)
         # Invalidate cache so next load_config() reads fresh data
         _CONFIG_CACHE = None
+        _CONFIG_MTIME = None
+        _CONFIG_SIZE = None
 
     @property
     def projects(self) -> Dict[str, str]:
@@ -891,33 +1042,50 @@ def save_basic_memory_config(file_path: Path, config: BasicMemoryConfig) -> None
 # Logging initialization functions for different entry points
 
 
-def init_cli_logging() -> None:  # pragma: no cover
+def _configure_logfire_for_entrypoint(entrypoint: str) -> None:
+    """Configure optional Logfire telemetry for a specific entrypoint."""
+    config = ConfigManager().config
+    service_name = f"{config.logfire_service_name}-{entrypoint}"
+    environment = config.logfire_environment or config.env
+    configure_telemetry(
+        service_name=service_name,
+        environment=environment,
+        service_version=__version__,
+        enable_logfire=config.logfire_enabled,
+        send_to_logfire=config.logfire_send_to_logfire,
+    )
+
+
+def init_cli_logging() -> None:
     """Initialize logging for CLI commands - file only.
 
     CLI commands should not log to stdout to avoid interfering with
     command output and shell integration.
     """
     log_level = os.getenv("BASIC_MEMORY_LOG_LEVEL", "INFO")
+    _configure_logfire_for_entrypoint("cli")
     setup_logging(log_level=log_level, log_to_file=True)
 
 
-def init_mcp_logging() -> None:  # pragma: no cover
+def init_mcp_logging() -> None:
     """Initialize logging for MCP server - file only.
 
     MCP server must not log to stdout as it would corrupt the
     JSON-RPC protocol communication.
     """
     log_level = os.getenv("BASIC_MEMORY_LOG_LEVEL", "INFO")
+    _configure_logfire_for_entrypoint("mcp")
     setup_logging(log_level=log_level, log_to_file=True)
 
 
-def init_api_logging() -> None:  # pragma: no cover
+def init_api_logging() -> None:
     """Initialize logging for API server.
 
     Cloud mode (BASIC_MEMORY_CLOUD_MODE=1): stdout with structured context
     Local mode: file only
     """
     log_level = os.getenv("BASIC_MEMORY_LOG_LEVEL", "INFO")
+    _configure_logfire_for_entrypoint("api")
     cloud_mode = os.getenv("BASIC_MEMORY_CLOUD_MODE", "").lower() in ("1", "true")
     if cloud_mode:
         setup_logging(log_level=log_level, log_to_stdout=True, structured_context=True)

src/basic_memory/db.py

@@ -43,104 +43,6 @@ if sys.platform == "win32":  # pragma: no cover
 _engine: Optional[AsyncEngine] = None
 _session_maker: Optional[async_sessionmaker[AsyncSession]] = None
 
-# Alembic revision that enables one-time automatic embedding backfill.
-SEMANTIC_EMBEDDING_BACKFILL_REVISION = "i2c3d4e5f6g7"
-
-
-async def _load_applied_alembic_revisions(
-    session_maker: async_sessionmaker[AsyncSession],
-) -> set[str]:
-    """Load applied Alembic revisions from alembic_version.
-
-    Returns an empty set when the version table does not exist yet
-    (fresh database before first migration).
-    """
-    try:
-        async with scoped_session(session_maker) as session:
-            result = await session.execute(text("SELECT version_num FROM alembic_version"))
-            return {str(row[0]) for row in result.fetchall() if row[0]}
-    except Exception as exc:
-        error_message = str(exc).lower()
-        if "alembic_version" in error_message and (
-            "no such table" in error_message or "does not exist" in error_message
-        ):
-            return set()
-        raise
-
-
-def _should_run_semantic_embedding_backfill(
-    revisions_before_upgrade: set[str],
-    revisions_after_upgrade: set[str],
-) -> bool:
-    """Check if this migration run newly applied the backfill-trigger revision."""
-    return (
-        SEMANTIC_EMBEDDING_BACKFILL_REVISION in revisions_after_upgrade
-        and SEMANTIC_EMBEDDING_BACKFILL_REVISION not in revisions_before_upgrade
-    )
-
-
-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."""
@@ -480,26 +382,9 @@ async def run_migrations(
     Note: Alembic tracks which migrations have been applied via the alembic_version table,
     so it's safe to call this multiple times - it will only run pending migrations.
     """
-    logger.debug("Running database migrations...")
+    logger.info("Running database migrations...")
     temp_engine: AsyncEngine | None = None
     try:
-        revisions_before_upgrade: set[str] = set()
-        # Trigger: run_migrations() can be invoked before module-level session maker is set.
-        # Why: we still need reliable before/after revision detection for one-time backfill.
-        # Outcome: create a short-lived session maker when needed, then dispose it immediately.
-        if _session_maker is None:
-            precheck_engine, temp_session_maker = _create_engine_and_session(
-                app_config.database_path,
-                database_type,
-                app_config,
-            )
-            try:
-                revisions_before_upgrade = await _load_applied_alembic_revisions(temp_session_maker)
-            finally:
-                await precheck_engine.dispose()
-        else:
-            revisions_before_upgrade = await _load_applied_alembic_revisions(_session_maker)
-
         # Get the absolute path to the alembic directory relative to this file
         alembic_dir = Path(__file__).parent / "alembic"
         config = Config()
@@ -519,7 +404,7 @@ async def run_migrations(
         config.set_main_option("sqlalchemy.url", db_url)
 
         command.upgrade(config, "head")
-        logger.debug("Migrations completed successfully")
+        logger.info("Migrations completed successfully")
 
         # Get session maker - ensure we don't trigger recursive migration calls
         if _session_maker is None:
@@ -541,12 +426,6 @@ async def run_migrations(
         else:
             await SQLiteSearchRepository(session_maker, 1).init_search_index()
 
-        revisions_after_upgrade = await _load_applied_alembic_revisions(session_maker)
-        if _should_run_semantic_embedding_backfill(
-            revisions_before_upgrade,
-            revisions_after_upgrade,
-        ):
-            await _run_semantic_embedding_backfill(app_config, session_maker)
     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)
 
@@ -447,6 +460,11 @@ def sanitize_for_filename(text: str, replacement: str = "-") -> str:
     # compress multiple, repeated replacements
     text = re.sub(f"{re.escape(replacement)}+", replacement, text)
 
+    # Strip trailing periods — they cause "hi-everyone..md" double-dot filenames
+    # when ".md" is appended, which triggers path traversal false positives.
+    # Trailing periods are also invalid on Windows filesystems.
+    text = text.strip(".")
+
     return text.strip(replacement)
 
 

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

@@ -5,6 +5,7 @@ from typing import AsyncIterator, Callable, Optional
 from httpx import ASGITransport, AsyncClient, Timeout
 from loguru import logger
 
+from basic_memory import telemetry
 from basic_memory.api.app import app as fastapi_app
 from basic_memory.config import ConfigManager, ProjectMode
 
@@ -43,21 +44,47 @@ def _asgi_client(timeout: Timeout) -> AsyncClient:
 
 async def _resolve_cloud_token(config) -> str:
     """Resolve cloud token with API key preferred, OAuth fallback."""
-    token = config.cloud_api_key
-    if token:
-        return token
+    with telemetry.span(
+        "routing.resolve_cloud_credentials",
+        has_api_key=bool(config.cloud_api_key),
+    ):
+        token = config.cloud_api_key
+        if token:
+            return token
 
-    from basic_memory.cli.auth import CLIAuth
+        from basic_memory.cli.auth import CLIAuth
 
-    auth = CLIAuth(client_id=config.cloud_client_id, authkit_domain=config.cloud_domain)
-    token = await auth.get_valid_token()
-    if token:
-        return token
+        auth = CLIAuth(client_id=config.cloud_client_id, authkit_domain=config.cloud_domain)
+        token = await auth.get_valid_token()
+        if token:
+            return token
 
-    raise RuntimeError(
-        "Cloud routing requested but no credentials found. "
-        "Run 'bm cloud api-key save <key>' or 'bm cloud login' first."
-    )
+        logger.error("Cloud routing requested but no credentials were available")
+        raise RuntimeError(
+            "Cloud routing requested but no credentials found. "
+            "Run 'bm cloud api-key save <key>' or 'bm cloud login' first."
+        )
+
+
+def resolve_configured_workspace(
+    *,
+    config=None,
+    project_name: Optional[str] = None,
+    workspace: Optional[str] = None,
+) -> Optional[str]:
+    """Resolve workspace from explicit input, per-project config, then global default."""
+    if workspace is not None:
+        return workspace
+
+    if config is None:
+        config = ConfigManager().config
+
+    if project_name is not None:
+        project_entry = config.projects.get(project_name)
+        if project_entry and project_entry.workspace_id:
+            return project_entry.workspace_id
+
+    return config.default_workspace
 
 
 @asynccontextmanager
@@ -82,25 +109,33 @@ async def _cloud_client(
 
 
 @asynccontextmanager
-async def get_cloud_control_plane_client() -> AsyncIterator[AsyncClient]:
+async def get_cloud_control_plane_client(
+    workspace: Optional[str] = None,
+) -> AsyncIterator[AsyncClient]:
     """Create a control-plane cloud client for endpoints outside /proxy."""
     config = ConfigManager().config
     timeout = _build_timeout()
     token = await _resolve_cloud_token(config)
+    headers = {"Authorization": f"Bearer {token}"}
+    if workspace:
+        headers["X-Workspace-ID"] = workspace
     logger.info(f"Creating HTTP client for cloud control plane at: {config.cloud_host}")
     async with AsyncClient(
         base_url=config.cloud_host,
-        headers={"Authorization": f"Bearer {token}"},
+        headers=headers,
         timeout=timeout,
     ) as 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
@@ -141,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
 
@@ -161,7 +196,12 @@ async def get_client(
 
         if _force_cloud_mode():
             logger.debug("Explicit cloud routing enabled - using cloud proxy client")
-            async with _cloud_client(config, timeout, workspace=workspace) as client:
+            effective_workspace = resolve_configured_workspace(
+                config=config,
+                project_name=project_name,
+                workspace=workspace,
+            )
+            async with _cloud_client(config, timeout, workspace=effective_workspace) as client:
                 yield client
             return
 
@@ -173,8 +213,13 @@ async def get_client(
         project_mode = config.get_project_mode(project_name)
         if project_mode == ProjectMode.CLOUD:
             logger.debug(f"Project '{project_name}' is cloud mode - using cloud proxy client")
+            effective_workspace = resolve_configured_workspace(
+                config=config,
+                project_name=project_name,
+                workspace=workspace,
+            )
             try:
-                async with _cloud_client(config, timeout, workspace=workspace) as client:
+                async with _cloud_client(config, timeout, workspace=effective_workspace) as client:
                     yield client
             except RuntimeError as exc:
                 raise RuntimeError(

src/basic_memory/mcp/clients/knowledge.py

@@ -7,6 +7,7 @@ from typing import Any
 
 from httpx import AsyncClient
 
+from basic_memory import telemetry
 from basic_memory.mcp.tools.utils import call_get, call_post, call_put, call_patch, call_delete
 from basic_memory.schemas.response import (
     EntityResponse,
@@ -58,12 +59,21 @@ class KnowledgeClient:
             ToolError: If the request fails
         """
         params = {"fast": fast} if fast is not None else None
-        response = await call_post(
-            self.http_client,
-            f"{self._base_path}/entities",
-            json=entity_data,
-            params=params,
-        )
+        with telemetry.scope(
+            "mcp.client.knowledge.create_entity",
+            client_name="knowledge",
+            operation="create_entity",
+            fast=fast,
+        ):
+            response = await call_post(
+                self.http_client,
+                f"{self._base_path}/entities",
+                json=entity_data,
+                params=params,
+                client_name="knowledge",
+                operation="create_entity",
+                path_template="/v2/projects/{project_id}/knowledge/entities",
+            )
         return EntityResponse.model_validate(response.json())
 
     async def update_entity(
@@ -86,12 +96,21 @@ class KnowledgeClient:
             ToolError: If the request fails
         """
         params = {"fast": fast} if fast is not None else None
-        response = await call_put(
-            self.http_client,
-            f"{self._base_path}/entities/{entity_id}",
-            json=entity_data,
-            params=params,
-        )
+        with telemetry.scope(
+            "mcp.client.knowledge.update_entity",
+            client_name="knowledge",
+            operation="update_entity",
+            fast=fast,
+        ):
+            response = await call_put(
+                self.http_client,
+                f"{self._base_path}/entities/{entity_id}",
+                json=entity_data,
+                params=params,
+                client_name="knowledge",
+                operation="update_entity",
+                path_template="/v2/projects/{project_id}/knowledge/entities/{entity_id}",
+            )
         return EntityResponse.model_validate(response.json())
 
     async def get_entity(self, entity_id: str) -> EntityResponse:
@@ -106,10 +125,18 @@ class KnowledgeClient:
         Raises:
             ToolError: If the entity is not found or request fails
         """
-        response = await call_get(
-            self.http_client,
-            f"{self._base_path}/entities/{entity_id}",
-        )
+        with telemetry.scope(
+            "mcp.client.knowledge.get_entity",
+            client_name="knowledge",
+            operation="get_entity",
+        ):
+            response = await call_get(
+                self.http_client,
+                f"{self._base_path}/entities/{entity_id}",
+                client_name="knowledge",
+                operation="get_entity",
+                path_template="/v2/projects/{project_id}/knowledge/entities/{entity_id}",
+            )
         return EntityResponse.model_validate(response.json())
 
     async def patch_entity(
@@ -132,12 +159,21 @@ class KnowledgeClient:
             ToolError: If the request fails
         """
         params = {"fast": fast} if fast is not None else None
-        response = await call_patch(
-            self.http_client,
-            f"{self._base_path}/entities/{entity_id}",
-            json=patch_data,
-            params=params,
-        )
+        with telemetry.scope(
+            "mcp.client.knowledge.patch_entity",
+            client_name="knowledge",
+            operation="patch_entity",
+            fast=fast,
+        ):
+            response = await call_patch(
+                self.http_client,
+                f"{self._base_path}/entities/{entity_id}",
+                json=patch_data,
+                params=params,
+                client_name="knowledge",
+                operation="patch_entity",
+                path_template="/v2/projects/{project_id}/knowledge/entities/{entity_id}",
+            )
         return EntityResponse.model_validate(response.json())
 
     async def delete_entity(self, entity_id: str) -> DeleteEntitiesResponse:
@@ -152,10 +188,18 @@ class KnowledgeClient:
         Raises:
             ToolError: If the entity is not found or request fails
         """
-        response = await call_delete(
-            self.http_client,
-            f"{self._base_path}/entities/{entity_id}",
-        )
+        with telemetry.scope(
+            "mcp.client.knowledge.delete_entity",
+            client_name="knowledge",
+            operation="delete_entity",
+        ):
+            response = await call_delete(
+                self.http_client,
+                f"{self._base_path}/entities/{entity_id}",
+                client_name="knowledge",
+                operation="delete_entity",
+                path_template="/v2/projects/{project_id}/knowledge/entities/{entity_id}",
+            )
         return DeleteEntitiesResponse.model_validate(response.json())
 
     async def move_entity(self, entity_id: str, destination_path: str) -> EntityResponse:
@@ -171,11 +215,19 @@ class KnowledgeClient:
         Raises:
             ToolError: If the request fails
         """
-        response = await call_put(
-            self.http_client,
-            f"{self._base_path}/entities/{entity_id}/move",
-            json={"destination_path": destination_path},
-        )
+        with telemetry.scope(
+            "mcp.client.knowledge.move_entity",
+            client_name="knowledge",
+            operation="move_entity",
+        ):
+            response = await call_put(
+                self.http_client,
+                f"{self._base_path}/entities/{entity_id}/move",
+                json={"destination_path": destination_path},
+                client_name="knowledge",
+                operation="move_entity",
+                path_template="/v2/projects/{project_id}/knowledge/entities/{entity_id}/move",
+            )
         return EntityResponse.model_validate(response.json())
 
     async def move_directory(
@@ -193,14 +245,22 @@ class KnowledgeClient:
         Raises:
             ToolError: If the request fails
         """
-        response = await call_post(
-            self.http_client,
-            f"{self._base_path}/move-directory",
-            json={
-                "source_directory": source_directory,
-                "destination_directory": destination_directory,
-            },
-        )
+        with telemetry.scope(
+            "mcp.client.knowledge.move_directory",
+            client_name="knowledge",
+            operation="move_directory",
+        ):
+            response = await call_post(
+                self.http_client,
+                f"{self._base_path}/move-directory",
+                json={
+                    "source_directory": source_directory,
+                    "destination_directory": destination_directory,
+                },
+                client_name="knowledge",
+                operation="move_directory",
+                path_template="/v2/projects/{project_id}/knowledge/move-directory",
+            )
         return DirectoryMoveResult.model_validate(response.json())
 
     async def delete_directory(self, directory: str) -> DirectoryDeleteResult:
@@ -215,11 +275,19 @@ class KnowledgeClient:
         Raises:
             ToolError: If the request fails
         """
-        response = await call_post(
-            self.http_client,
-            f"{self._base_path}/delete-directory",
-            json={"directory": directory},
-        )
+        with telemetry.scope(
+            "mcp.client.knowledge.delete_directory",
+            client_name="knowledge",
+            operation="delete_directory",
+        ):
+            response = await call_post(
+                self.http_client,
+                f"{self._base_path}/delete-directory",
+                json={"directory": directory},
+                client_name="knowledge",
+                operation="delete_directory",
+                path_template="/v2/projects/{project_id}/knowledge/delete-directory",
+            )
         return DirectoryDeleteResult.model_validate(response.json())
 
     # --- Resolution ---
@@ -237,10 +305,18 @@ class KnowledgeClient:
         Raises:
             ToolError: If the identifier cannot be resolved
         """
-        response = await call_post(
-            self.http_client,
-            f"{self._base_path}/resolve",
-            json={"identifier": identifier, "strict": strict},
-        )
+        with telemetry.scope(
+            "mcp.client.knowledge.resolve_entity",
+            client_name="knowledge",
+            operation="resolve_entity",
+        ):
+            response = await call_post(
+                self.http_client,
+                f"{self._base_path}/resolve",
+                json={"identifier": identifier, "strict": strict},
+                client_name="knowledge",
+                operation="resolve_entity",
+                path_template="/v2/projects/{project_id}/knowledge/resolve",
+            )
         data = response.json()
         return data["external_id"]

src/basic_memory/mcp/clients/memory.py

@@ -7,6 +7,7 @@ from typing import Optional
 
 from httpx import AsyncClient
 
+from basic_memory import telemetry
 from basic_memory.mcp.tools.utils import call_get
 from basic_memory.schemas.memory import GraphContext
 
@@ -71,11 +72,21 @@ class MemoryClient:
         if timeframe:
             params["timeframe"] = timeframe
 
-        response = await call_get(
-            self.http_client,
-            f"{self._base_path}/{path}",
-            params=params,
-        )
+        with telemetry.scope(
+            "mcp.client.memory.build_context",
+            client_name="memory",
+            operation="build_context",
+            page=page,
+            page_size=page_size,
+        ):
+            response = await call_get(
+                self.http_client,
+                f"{self._base_path}/{path}",
+                params=params,
+                client_name="memory",
+                operation="build_context",
+                path_template="/v2/projects/{project_id}/memory/{path}",
+            )
         return GraphContext.model_validate(response.json())
 
     async def recent(
@@ -112,9 +123,19 @@ class MemoryClient:
             # Join types as comma-separated string if provided
             params["type"] = ",".join(types) if isinstance(types, list) else types
 
-        response = await call_get(
-            self.http_client,
-            f"{self._base_path}/recent",
-            params=params,
-        )
+        with telemetry.scope(
+            "mcp.client.memory.recent_activity",
+            client_name="memory",
+            operation="recent_activity",
+            page=page,
+            page_size=page_size,
+        ):
+            response = await call_get(
+                self.http_client,
+                f"{self._base_path}/recent",
+                params=params,
+                client_name="memory",
+                operation="recent_activity",
+                path_template="/v2/projects/{project_id}/memory/recent",
+            )
         return GraphContext.model_validate(response.json())

src/basic_memory/mcp/clients/resource.py

@@ -7,6 +7,7 @@ from typing import Optional
 
 from httpx import AsyncClient, Response
 
+from basic_memory import telemetry
 from basic_memory.mcp.tools.utils import call_get
 
 
@@ -64,8 +65,18 @@ class ResourceClient:
         if page_size is not None:
             params["page_size"] = page_size
 
-        return await call_get(
-            self.http_client,
-            f"{self._base_path}/{entity_id}",
-            params=params if params else None,
-        )
+        with telemetry.scope(
+            "mcp.client.resource.read",
+            client_name="resource",
+            operation="read",
+            page=page,
+            page_size=page_size,
+        ):
+            return await call_get(
+                self.http_client,
+                f"{self._base_path}/{entity_id}",
+                params=params if params else None,
+                client_name="resource",
+                operation="read",
+                path_template="/v2/projects/{project_id}/resource/{entity_id}",
+            )

src/basic_memory/mcp/clients/search.py

@@ -7,6 +7,7 @@ from typing import Any
 
 from httpx import AsyncClient
 
+from basic_memory import telemetry
 from basic_memory.mcp.tools.utils import call_post
 from basic_memory.schemas.search import SearchResponse
 
@@ -56,10 +57,20 @@ class SearchClient:
         Raises:
             ToolError: If the request fails
         """
-        response = await call_post(
-            self.http_client,
-            f"{self._base_path}/",
-            json=query,
-            params={"page": page, "page_size": page_size},
-        )
+        with telemetry.scope(
+            "mcp.client.search.search",
+            client_name="search",
+            operation="search",
+            page=page,
+            page_size=page_size,
+        ):
+            response = await call_post(
+                self.http_client,
+                f"{self._base_path}/",
+                json=query,
+                params={"page": page, "page_size": page_size},
+                client_name="search",
+                operation="search",
+                path_template="/v2/projects/{project_id}/search/",
+            )
         return SearchResponse.model_validate(response.json())

src/basic_memory/mcp/project_context.py

@@ -19,6 +19,7 @@ from loguru import logger
 from fastmcp import Context
 from mcp.server.fastmcp.exceptions import ToolError
 
+from basic_memory import telemetry
 from basic_memory.config import BasicMemoryConfig, ConfigManager, ProjectMode
 from basic_memory.project_resolver import ProjectResolver
 from basic_memory.schemas.cloud import WorkspaceInfo, WorkspaceListResponse
@@ -63,10 +64,79 @@ async def _resolve_default_project_from_api() -> Optional[str]:
     return None
 
 
+async def _get_cached_active_project(context: Optional[Context]) -> Optional[ProjectItem]:
+    """Return the cached active project from context when available."""
+    if not context:
+        return None
+
+    cached_raw = await context.get_state("active_project")
+    if isinstance(cached_raw, dict):
+        return ProjectItem.model_validate(cached_raw)
+    return None
+
+
+async def _set_cached_active_project(
+    context: Optional[Context],
+    active_project: ProjectItem,
+) -> None:
+    """Persist the active project and known default-project metadata in context."""
+    if not context:
+        return
+
+    await context.set_state("active_project", active_project.model_dump())
+    if active_project.is_default:
+        await context.set_state("default_project_name", active_project.name)
+
+
+async def _get_cached_default_project(context: Optional[Context]) -> Optional[str]:
+    """Return the cached default project name from context when available."""
+    if not context:
+        return None
+
+    cached_default = await context.get_state("default_project_name")
+    if isinstance(cached_default, str):
+        return cached_default
+    return None
+
+
+def _canonicalize_project_name(
+    project_name: Optional[str],
+    config: BasicMemoryConfig,
+) -> Optional[str]:
+    """Return the configured project name when the identifier matches by permalink.
+
+    Project routing happens before API validation, so we normalize explicit inputs
+    here to keep local/cloud routing aligned with the database's case-insensitive
+    project resolver.
+    """
+    if project_name is None:
+        return None
+
+    requested_permalink = generate_permalink(project_name)
+    for configured_name in config.projects:
+        if generate_permalink(configured_name) == requested_permalink:
+            return configured_name
+
+    return project_name
+
+
+def _project_matches_identifier(project_item: ProjectItem, identifier: Optional[str]) -> bool:
+    """Return True when the identifier refers to the cached project."""
+    if identifier is None:
+        return True
+
+    normalized_identifier = generate_permalink(identifier)
+    return normalized_identifier in {
+        generate_permalink(project_item.name),
+        project_item.permalink,
+    }
+
+
 async def resolve_project_parameter(
     project: Optional[str] = None,
     allow_discovery: bool = False,
     default_project: Optional[str] = None,
+    context: Optional[Context] = None,
 ) -> Optional[str]:
     """Resolve project parameter using unified linear priority chain.
 
@@ -89,22 +159,46 @@ async def resolve_project_parameter(
     Returns:
         Resolved project name or None if no resolution possible
     """
-    # Load config for any values not explicitly provided.
-    # ConfigManager reads from the local config file, which doesn't exist in cloud mode.
-    # When it returns None, fall back to querying the projects API for the is_default flag.
-    if default_project is None:
+    with telemetry.span(
+        "routing.resolve_project",
+        requested_project=project,
+        allow_discovery=allow_discovery,
+    ):
         config = ConfigManager().config
-        default_project = config.default_project
 
-    if default_project is None:
-        default_project = await _resolve_default_project_from_api()
+        # Trigger: project already resolved earlier in the same MCP request
+        # Why: the active project is request-constant, so re-discovering the
+        #   default project via /v2/projects/ just repeats work
+        # Outcome: reuse the cached project name as the explicit candidate
+        if project is None:
+            cached_project = await _get_cached_active_project(context)
+            if cached_project is not None:
+                project = cached_project.name
 
-    # Create resolver with configuration and resolve
-    resolver = ProjectResolver.from_env(
-        default_project=default_project,
-    )
-    result = resolver.resolve(project=project, allow_discovery=allow_discovery)
-    return result.project
+        # Trigger: there is no explicit project after env/context normalization
+        # Why: default-project discovery is only needed as a fallback; doing it
+        #   for explicit requests adds an avoidable /v2/projects/ round-trip
+        # Outcome: skip default lookup when the active project is already known
+        if default_project is None and project is None:
+            # Load config for any values not explicitly provided.
+            # ConfigManager reads from the local config file, which doesn't exist in cloud mode.
+            # When it returns None, fall back to querying the projects API for the is_default flag.
+            default_project = config.default_project
+
+            if default_project is None:
+                default_project = await _get_cached_default_project(context)
+
+            if default_project is None:
+                default_project = await _resolve_default_project_from_api()
+                if default_project and context:
+                    await context.set_state("default_project_name", default_project)
+
+        # Create resolver with configuration and resolve
+        resolver = ProjectResolver.from_env(
+            default_project=default_project,
+        )
+        result = resolver.resolve(project=project, allow_discovery=allow_discovery)
+        return _canonicalize_project_name(result.project, config)
 
 
 async def get_project_names(client: AsyncClient, headers: HeaderTypes | None = None) -> List[str]:
@@ -177,51 +271,60 @@ async def resolve_workspace_parameter(
     context: Optional[Context] = None,
 ) -> WorkspaceInfo:
     """Resolve workspace using explicit input, session cache, and cloud discovery."""
-    if context:
-        cached_raw = await context.get_state("active_workspace")
-        if isinstance(cached_raw, dict):
-            cached_workspace = WorkspaceInfo.model_validate(cached_raw)
-            if workspace is None or _workspace_matches_identifier(cached_workspace, workspace):
-                logger.debug(f"Using cached workspace from context: {cached_workspace.tenant_id}")
-                return cached_workspace
+    with telemetry.scope(
+        "routing.resolve_workspace",
+        workspace_requested=workspace is not None,
+        has_context=context is not None,
+    ):
+        if context:
+            cached_raw = await context.get_state("active_workspace")
+            if isinstance(cached_raw, dict):
+                cached_workspace = WorkspaceInfo.model_validate(cached_raw)
+                if workspace is None or _workspace_matches_identifier(cached_workspace, workspace):
+                    logger.debug(
+                        f"Using cached workspace from context: {cached_workspace.tenant_id}"
+                    )
+                    return cached_workspace
 
-    workspaces = await get_available_workspaces(context=context)
-    if not workspaces:
-        raise ValueError(
-            "No accessible workspaces found for this account. "
-            "Ensure you have an active subscription and tenant access."
-        )
-
-    selected_workspace: WorkspaceInfo | None = None
-
-    if workspace:
-        matches = [item for item in workspaces if _workspace_matches_identifier(item, workspace)]
-        if not matches:
+        workspaces = await get_available_workspaces(context=context)
+        if not workspaces:
             raise ValueError(
-                f"Workspace '{workspace}' was not found.\n"
+                "No accessible workspaces found for this account. "
+                "Ensure you have an active subscription and tenant access."
+            )
+
+        selected_workspace: WorkspaceInfo | None = None
+
+        if workspace:
+            matches = [
+                item for item in workspaces if _workspace_matches_identifier(item, workspace)
+            ]
+            if not matches:
+                raise ValueError(
+                    f"Workspace '{workspace}' was not found.\n"
+                    f"Available workspaces:\n{_workspace_choices(workspaces)}"
+                )
+            if len(matches) > 1:
+                raise ValueError(
+                    f"Workspace name '{workspace}' matches multiple workspaces. "
+                    "Use tenant_id instead.\n"
+                    f"Available workspaces:\n{_workspace_choices(workspaces)}"
+                )
+            selected_workspace = matches[0]
+        elif len(workspaces) == 1:
+            selected_workspace = workspaces[0]
+        else:
+            raise ValueError(
+                "Multiple workspaces are available. Ask the user which workspace to use, then retry "
+                "with the 'workspace' argument set to the tenant_id or unique name.\n"
                 f"Available workspaces:\n{_workspace_choices(workspaces)}"
             )
-        if len(matches) > 1:
-            raise ValueError(
-                f"Workspace name '{workspace}' matches multiple workspaces. "
-                "Use tenant_id instead.\n"
-                f"Available workspaces:\n{_workspace_choices(workspaces)}"
-            )
-        selected_workspace = matches[0]
-    elif len(workspaces) == 1:
-        selected_workspace = workspaces[0]
-    else:
-        raise ValueError(
-            "Multiple workspaces are available. Ask the user which workspace to use, then retry "
-            "with the 'workspace' argument set to the tenant_id or unique name.\n"
-            f"Available workspaces:\n{_workspace_choices(workspaces)}"
-        )
 
-    if context:
-        await context.set_state("active_workspace", selected_workspace.model_dump())
-        logger.debug(f"Cached workspace in context: {selected_workspace.tenant_id}")
+        if context:
+            await context.set_state("active_workspace", selected_workspace.model_dump())
+            logger.debug(f"Cached workspace in context: {selected_workspace.tenant_id}")
 
-    return selected_workspace
+        return selected_workspace
 
 
 async def get_active_project(
@@ -244,53 +347,58 @@ async def get_active_project(
         ValueError: If no project can be resolved
         HTTPError: If project doesn't exist or is inaccessible
     """
-    # Deferred import to avoid circular dependency with tools
-    from basic_memory.mcp.tools.utils import call_post
+    with telemetry.scope(
+        "routing.validate_project",
+        requested_project=project,
+        has_context=context is not None,
+    ):
+        # Deferred import to avoid circular dependency with tools
+        from basic_memory.mcp.tools.utils import call_post
 
-    resolved_project = await resolve_project_parameter(project)
-    if not resolved_project:
-        project_names = await get_project_names(client, headers)
-        raise ValueError(
-            "No project specified. "
-            "Either set 'default_project' in config, or use 'project' argument.\n"
-            f"Available projects: {project_names}"
+        cached_project = await _get_cached_active_project(context)
+        if cached_project and _project_matches_identifier(cached_project, project):
+            logger.debug(f"Using cached project from context: {cached_project.name}")
+            return cached_project
+
+        resolved_project = await resolve_project_parameter(project, context=context)
+        if not resolved_project:
+            project_names = await get_project_names(client, headers)
+            raise ValueError(
+                "No project specified. "
+                "Either set 'default_project' in config, or use 'project' argument.\n"
+                f"Available projects: {project_names}"
+            )
+
+        project = resolved_project
+
+        if cached_project and _project_matches_identifier(cached_project, project):
+            logger.debug(f"Using cached project from context: {cached_project.name}")
+            return cached_project
+
+        # Validate project exists by calling API
+        logger.debug(f"Validating project: {project}")
+        response = await call_post(
+            client,
+            "/v2/projects/resolve",
+            json={"identifier": project},
+            headers=headers,
+        )
+        resolved = ProjectResolveResponse.model_validate(response.json())
+        active_project = ProjectItem(
+            id=resolved.project_id,
+            external_id=resolved.external_id,
+            name=resolved.name,
+            path=resolved.path,
+            is_default=resolved.is_default,
         )
 
-    project = resolved_project
+        # Cache in context if available
+        await _set_cached_active_project(context, active_project)
+        if context:
+            logger.debug(f"Cached project in context: {project}")
 
-    # Check if already cached in context
-    if context:
-        cached_raw = await context.get_state("active_project")
-        if isinstance(cached_raw, dict):
-            cached_project = ProjectItem.model_validate(cached_raw)
-            if cached_project.name == project:
-                logger.debug(f"Using cached project from context: {project}")
-                return cached_project
-
-    # Validate project exists by calling API
-    logger.debug(f"Validating project: {project}")
-    response = await call_post(
-        client,
-        "/v2/projects/resolve",
-        json={"identifier": project},
-        headers=headers,
-    )
-    resolved = ProjectResolveResponse.model_validate(response.json())
-    active_project = ProjectItem(
-        id=resolved.project_id,
-        external_id=resolved.external_id,
-        name=resolved.name,
-        path=resolved.path,
-        is_default=resolved.is_default,
-    )
-
-    # Cache in context if available
-    if context:
-        await context.set_state("active_project", active_project.model_dump())
-        logger.debug(f"Cached project in context: {project}")
-
-    logger.debug(f"Validated project: {active_project.name}")
-    return active_project
+        logger.debug(f"Validated project: {active_project.name}")
+        return active_project
 
 
 def _split_project_prefix(path: str) -> tuple[Optional[str], str]:
@@ -321,66 +429,91 @@ async def resolve_project_and_path(
         Tuple of (active_project, normalized_path, is_memory_url)
     """
     is_memory_url = identifier.strip().startswith("memory://")
-    if not is_memory_url:
-        active_project = await get_active_project(client, project, context, headers)
-        return active_project, identifier, False
+    config = ConfigManager().config
+    include_project = config.permalinks_include_project if is_memory_url else None
+    with telemetry.scope(
+        "routing.resolve_memory_url",
+        is_memory_url=is_memory_url,
+        requested_project=project,
+        include_project_prefix=include_project,
+    ):
+        if not is_memory_url:
+            active_project = await get_active_project(client, project, context, headers)
+            return active_project, identifier, False
 
-    normalized_path = normalize_project_reference(memory_url_path(identifier))
-    project_prefix, remainder = _split_project_prefix(normalized_path)
-    include_project = ConfigManager().config.permalinks_include_project
+        normalized_path = normalize_project_reference(memory_url_path(identifier))
+        project_prefix, remainder = _split_project_prefix(normalized_path)
+        include_project = config.permalinks_include_project
+        # Trigger: memory URL begins with a potential project segment
+        # Why: allow project-scoped memory URLs without requiring a separate project parameter
+        # Outcome: attempt to resolve the prefix as a project and route to it
+        if project_prefix:
+            cached_project = await _get_cached_active_project(context)
+            if cached_project and _project_matches_identifier(cached_project, project_prefix):
+                resolved_project = await resolve_project_parameter(project_prefix, context=context)
+                if resolved_project and generate_permalink(resolved_project) != generate_permalink(
+                    project_prefix
+                ):
+                    raise ValueError(
+                        f"Project is constrained to '{resolved_project}', cannot use '{project_prefix}'."
+                    )
 
-    # Trigger: memory URL begins with a potential project segment
-    # Why: allow project-scoped memory URLs without requiring a separate project parameter
-    # Outcome: attempt to resolve the prefix as a project and route to it
-    if project_prefix:
-        try:
-            from basic_memory.mcp.tools.utils import call_post
-
-            response = await call_post(
-                client,
-                "/v2/projects/resolve",
-                json={"identifier": project_prefix},
-                headers=headers,
-            )
-            resolved = ProjectResolveResponse.model_validate(response.json())
-        except ToolError as exc:
-            if "project not found" not in str(exc).lower():
-                raise
-        else:
-            resolved_project = await resolve_project_parameter(project_prefix)
-            if resolved_project and generate_permalink(resolved_project) != generate_permalink(
-                project_prefix
-            ):
-                raise ValueError(
-                    f"Project is constrained to '{resolved_project}', cannot use '{project_prefix}'."
+                resolved_path = (
+                    f"{cached_project.permalink}/{remainder}" if include_project else remainder
                 )
+                return cached_project, resolved_path, True
 
-            active_project = ProjectItem(
-                id=resolved.project_id,
-                external_id=resolved.external_id,
-                name=resolved.name,
-                path=resolved.path,
-                is_default=resolved.is_default,
-            )
-            if context:
-                await context.set_state("active_project", active_project.model_dump())
+            try:
+                from basic_memory.mcp.tools.utils import call_post
 
-            resolved_path = f"{resolved.permalink}/{remainder}" if include_project else remainder
-            return active_project, resolved_path, True
+                response = await call_post(
+                    client,
+                    "/v2/projects/resolve",
+                    json={"identifier": project_prefix},
+                    headers=headers,
+                )
+                resolved = ProjectResolveResponse.model_validate(response.json())
+            except ToolError as exc:
+                if "project not found" not in str(exc).lower():
+                    raise
+            else:
+                resolved_project = await resolve_project_parameter(project_prefix, context=context)
+                if resolved_project and generate_permalink(resolved_project) != generate_permalink(
+                    project_prefix
+                ):
+                    raise ValueError(
+                        f"Project is constrained to '{resolved_project}', cannot use '{project_prefix}'."
+                    )
 
-    # Trigger: no resolvable project prefix in the memory URL
-    # Why: preserve existing memory URL behavior within the active project
-    # Outcome: use the active project and normalize the path for lookup
-    active_project = await get_active_project(client, project, context, headers)
-    resolved_path = normalized_path
-    if include_project:
-        # Trigger: project-prefixed permalinks are enabled and the path lacks a prefix
-        # Why: ensure memory URL lookups align with canonical permalinks
-        # Outcome: prefix the path with the active project's permalink
-        project_prefix = active_project.permalink
-        if resolved_path != project_prefix and not resolved_path.startswith(f"{project_prefix}/"):
-            resolved_path = f"{project_prefix}/{resolved_path}"
-    return active_project, resolved_path, True
+                active_project = ProjectItem(
+                    id=resolved.project_id,
+                    external_id=resolved.external_id,
+                    name=resolved.name,
+                    path=resolved.path,
+                    is_default=resolved.is_default,
+                )
+                await _set_cached_active_project(context, active_project)
+
+                resolved_path = (
+                    f"{resolved.permalink}/{remainder}" if include_project else remainder
+                )
+                return active_project, resolved_path, True
+
+        # Trigger: no resolvable project prefix in the memory URL
+        # Why: preserve existing memory URL behavior within the active project
+        # Outcome: use the active project and normalize the path for lookup
+        active_project = await get_active_project(client, project, context, headers)
+        resolved_path = normalized_path
+        if include_project:
+            # Trigger: project-prefixed permalinks are enabled and the path lacks a prefix
+            # Why: ensure memory URL lookups align with canonical permalinks
+            # Outcome: prefix the path with the active project's permalink
+            project_prefix = active_project.permalink
+            if resolved_path != project_prefix and not resolved_path.startswith(
+                f"{project_prefix}/"
+            ):
+                resolved_path = f"{project_prefix}/{resolved_path}"
+        return active_project, resolved_path, True
 
 
 def add_project_metadata(result: str, project_name: str) -> str:
@@ -476,7 +609,7 @@ async def get_project_client(
     )
 
     # Step 1: Resolve project name from config (no network call)
-    resolved_project = await resolve_project_parameter(project)
+    resolved_project = await resolve_project_parameter(project, context=context)
     if not resolved_project:
         # Fall back to local client to discover projects and raise helpful error
         async with get_client() as client:
@@ -489,14 +622,22 @@ 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():
-        async with get_client() as client:
-            active_project = await get_active_project(client, resolved_project, context)
-            yield client, active_project
+        route_mode = "factory"
+        with telemetry.scope(
+            "routing.client_session",
+            project_name=resolved_project,
+            route_mode=route_mode,
+            workspace_id=workspace,
+        ):
+            logger.debug("Using injected client factory for project routing")
+            async with get_client(workspace=workspace) as client:
+                active_project = await get_active_project(client, resolved_project, context)
+                yield client, active_project
         return
 
     # Step 2: Check explicit routing BEFORE workspace resolution
@@ -504,9 +645,16 @@ async def get_project_client(
     # Why: explicit flags must be deterministic — skip workspace entirely for --local
     # Outcome: route strictly based on explicit flag, no workspace network calls
     if _explicit_routing() and _force_local_mode():
-        async with get_client(project_name=resolved_project) as client:
-            active_project = await get_active_project(client, resolved_project, context)
-            yield client, active_project
+        route_mode = "explicit_local"
+        with telemetry.scope(
+            "routing.client_session",
+            project_name=resolved_project,
+            route_mode=route_mode,
+        ):
+            logger.debug("Explicit local routing selected for project client")
+            async with get_client(project_name=resolved_project) as client:
+                active_project = await get_active_project(client, resolved_project, context)
+                yield client, active_project
         return
 
     # Step 3: Determine if cloud routing is needed
@@ -535,28 +683,51 @@ async def get_project_client(
         if effective_workspace is None and config.default_workspace:
             effective_workspace = config.default_workspace
 
+        route_mode = "cloud_proxy"
+
         # Priorities 4-6: if still unresolved, fall back to resolve_workspace_parameter
         # which checks context cache, auto-selects single workspace, or errors
         if effective_workspace is not None:
             # Config-resolved workspace — pass directly to get_client, skip network lookup
-            async with get_client(
+            with telemetry.scope(
+                "routing.client_session",
                 project_name=resolved_project,
-                workspace=effective_workspace,
-            ) as client:
-                active_project = await get_active_project(client, resolved_project, context)
-                yield client, active_project
+                route_mode=route_mode,
+                workspace_id=effective_workspace,
+            ):
+                logger.debug("Using configured workspace for cloud project routing")
+                async with get_client(
+                    project_name=resolved_project,
+                    workspace=effective_workspace,
+                ) as client:
+                    active_project = await get_active_project(client, resolved_project, context)
+                    yield client, active_project
         else:
             # No config-based workspace — use resolve_workspace_parameter for discovery
             active_ws = await resolve_workspace_parameter(workspace=None, context=context)
-            async with get_client(
+            with telemetry.scope(
+                "routing.client_session",
                 project_name=resolved_project,
-                workspace=active_ws.tenant_id,
-            ) as client:
-                active_project = await get_active_project(client, resolved_project, context)
-                yield client, active_project
+                route_mode=route_mode,
+                workspace_id=active_ws.tenant_id,
+            ):
+                logger.debug("Resolved workspace dynamically for cloud project routing")
+                async with get_client(
+                    project_name=resolved_project,
+                    workspace=active_ws.tenant_id,
+                ) as client:
+                    active_project = await get_active_project(client, resolved_project, context)
+                    yield client, active_project
         return
 
     # Step 4: Local routing (default)
-    async with get_client(project_name=resolved_project) as client:
-        active_project = await get_active_project(client, resolved_project, context)
-        yield client, active_project
+    route_mode = "local_asgi"
+    with telemetry.scope(
+        "routing.client_session",
+        project_name=resolved_project,
+        route_mode=route_mode,
+    ):
+        logger.debug("Using default local ASGI routing for project client")
+        async with get_client(project_name=resolved_project) as client:
+            active_project = await get_active_project(client, resolved_project, context)
+            yield client, active_project

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

@@ -7,11 +7,45 @@ from contextlib import asynccontextmanager
 
 from fastmcp import FastMCP
 from loguru import logger
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession
 
 from basic_memory import db
 from basic_memory.cli.auth import CLIAuth
+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
+
+
+async def _log_embedding_status(session_maker: async_sessionmaker[AsyncSession]) -> None:
+    """Log a clear summary of semantic embedding status at startup."""
+    try:
+        async with scoped_session(session_maker) as session:
+            entity_count = (
+                await session.execute(text("SELECT COUNT(*) FROM entity"))
+            ).scalar() or 0
+            chunk_count = (
+                await session.execute(text("SELECT COUNT(*) FROM search_vector_chunks"))
+            ).scalar() or 0
+            embedding_count = (
+                await session.execute(text("SELECT COUNT(*) FROM search_vector_embeddings_rowids"))
+            ).scalar() or 0
+
+        if entity_count == 0:
+            logger.info("Semantic embeddings: no entities yet")
+        elif embedding_count == 0:
+            logger.warning(
+                f"Semantic embeddings: EMPTY — {entity_count} entities have no embeddings. "
+                "Run 'bm reindex --embeddings' to build them."
+            )
+        else:
+            logger.info(
+                f"Semantic embeddings: {embedding_count} embeddings "
+                f"across {chunk_count} chunks for {entity_count} entities"
+            )
+    except Exception as exc:
+        logger.debug(f"Could not check embedding status at startup: {exc}")
 
 
 @asynccontextmanager
@@ -29,64 +63,82 @@ async def lifespan(app: FastMCP):
     set_container(container)
 
     config = container.config
-    logger.info(f"Starting Basic Memory MCP server (mode={container.mode.name})")
-    logger.info(
-        f"Config: database_backend={config.database_backend.value}, "
-        f"semantic_search_enabled={config.semantic_search_enabled}, "
-        f"default_project={config.default_project}"
-    )
-    if config.semantic_search_enabled:
+    with telemetry.operation(
+        "mcp.lifecycle.startup",
+        entrypoint="mcp",
+        mode=container.mode.name.lower(),
+        default_project=config.default_project,
+    ):
+        logger.info(f"Starting Basic Memory MCP server (mode={container.mode.name})")
         logger.info(
-            f"Semantic search: provider={config.semantic_embedding_provider}, "
-            f"model={config.semantic_embedding_model}, "
-            f"dimensions={config.semantic_embedding_dimensions or 'auto'}, "
-            f"batch_size={config.semantic_embedding_batch_size}"
+            f"Config: database_backend={config.database_backend.value}, "
+            f"semantic_search_enabled={config.semantic_search_enabled}, "
+            f"default_project={config.default_project}"
         )
+        if config.semantic_search_enabled:
+            logger.info(
+                f"Semantic search: provider={config.semantic_embedding_provider}, "
+                f"model={config.semantic_embedding_model}, "
+                f"dimensions={config.semantic_embedding_dimensions or 'auto'}, "
+                f"batch_size={config.semantic_embedding_batch_size}"
+            )
 
-    # Log configured projects with their routing mode
-    for name, entry in config.projects.items():
-        default = " (default)" if name == config.default_project else ""
-        logger.info(f"Project: {name} -> {entry.path} [mode={entry.mode.value}]{default}")
+        # Log configured projects with their routing mode
+        for name, entry in config.projects.items():
+            default = " (default)" if name == config.default_project else ""
+            logger.info(f"Project: {name} -> {entry.path} [mode={entry.mode.value}]{default}")
 
-    # Check cloud auth status (local file check, no network call)
-    auth = CLIAuth(client_id=config.cloud_client_id, authkit_domain=config.cloud_domain)
-    tokens = auth.load_tokens()
-    if tokens is not None:
-        if not auth.is_token_valid(tokens):
-            expires_at = tokens.get("expires_at", 0)
-            expired_ago = int(time.time() - expires_at)
-            logger.warning(f"Cloud token expired {expired_ago}s ago - may need 'bm cloud login'")
-        else:
-            logger.info("Cloud: authenticated (OAuth token valid)")
+        # Check cloud auth status (local file check, no network call)
+        auth = CLIAuth(client_id=config.cloud_client_id, authkit_domain=config.cloud_domain)
+        tokens = auth.load_tokens()
+        if tokens is not None:
+            if not auth.is_token_valid(tokens):
+                expires_at = tokens.get("expires_at", 0)
+                expired_ago = int(time.time() - expires_at)
+                logger.warning(
+                    f"Cloud token expired {expired_ago}s ago - may need 'bm cloud login'"
+                )
+            else:
+                logger.info("Cloud: authenticated (OAuth token valid)")
 
-    if config.cloud_api_key:
-        logger.info("Cloud: API key configured")
+        if config.cloud_api_key:
+            logger.info("Cloud: API key configured")
 
-    # Track if we created the engine (vs test fixtures providing it)
-    # This prevents disposing an engine provided by test fixtures when
-    # multiple Client connections are made in the same test
-    engine_was_none = db._engine is None
+        # Track if we created the engine (vs test fixtures providing it)
+        # This prevents disposing an engine provided by test fixtures when
+        # multiple Client connections are made in the same test
+        engine_was_none = db._engine is None
 
-    # Initialize app (runs migrations, reconciles projects)
-    await initialize_app(container.config)
+        # Initialize app (runs migrations, reconciles projects)
+        await initialize_app(container.config)
 
-    # Create and start sync coordinator (lifecycle centralized in coordinator)
-    sync_coordinator = container.create_sync_coordinator()
-    await sync_coordinator.start()
+        # Log embedding status so it's easy to spot in the logs
+        if config.semantic_search_enabled and db._session_maker is not None:
+            await _log_embedding_status(db._session_maker)
+
+        # Create and start sync coordinator (lifecycle centralized in coordinator)
+        sync_coordinator = container.create_sync_coordinator()
+        await sync_coordinator.start()
 
     try:
         yield
     finally:
         # Shutdown - coordinator handles clean task cancellation
-        logger.debug("Shutting down Basic Memory MCP server")
-        await sync_coordinator.stop()
+        with telemetry.operation(
+            "mcp.lifecycle.shutdown",
+            entrypoint="mcp",
+            mode=container.mode.name.lower(),
+        ):
+            logger.debug("Shutting down Basic Memory MCP server")
 
-        # Only shutdown DB if we created it (not if test fixture provided it)
-        if engine_was_none:
-            await db.shutdown_db()
-            logger.debug("Database connections closed")
-        else:  # pragma: no cover
-            logger.debug("Skipping DB shutdown - engine provided externally")
+            await sync_coordinator.stop()
+
+            # Only shutdown DB if we created it (not if test fixture provided it)
+            if engine_was_none:
+                await db.shutdown_db()
+                logger.debug("Database connections closed")
+            else:  # pragma: no cover
+                logger.debug("Skipping DB shutdown - engine provided externally")
 
 
 mcp = FastMCP(

src/basic_memory/mcp/tools/build_context.py

@@ -6,6 +6,7 @@ from loguru import logger
 from fastmcp import Context
 
 from basic_memory.config import ConfigManager
+from basic_memory import telemetry
 from basic_memory.mcp.project_context import (
     detect_project_from_url_prefix,
     get_project_client,
@@ -190,8 +191,6 @@ async def build_context(
         if detected:
             project = detected
 
-    logger.info(f"Building context from {url} in project {project}")
-
     # Convert string depth to integer if needed
     if isinstance(depth, str):
         try:
@@ -203,25 +202,62 @@ async def build_context(
 
     # URL is already validated and normalized by MemoryUrl type annotation
 
-    async with get_project_client(project, workspace, context) as (client, active_project):
-        # Resolve memory:// identifier with project-prefix awareness
-        _, resolved_path, _ = await resolve_project_and_path(client, url, project, context)
+    with telemetry.operation(
+        "mcp.tool.build_context",
+        entrypoint="mcp",
+        tool_name="build_context",
+        requested_project=project,
+        workspace_id=workspace,
+        depth=depth or 1,
+        timeframe=timeframe,
+        page=page,
+        page_size=page_size,
+        max_related=max_related,
+        output_format=output_format,
+        is_memory_url=str(url).startswith("memory://"),
+    ):
+        async with get_project_client(project, workspace, context) as (client, active_project):
+            with telemetry.contextualize(
+                project_name=active_project.name,
+                workspace_id=workspace,
+                tool_name="build_context",
+            ):
+                logger.info(
+                    f"MCP tool call tool=build_context project={active_project.name} "
+                    f"url={url} depth={depth} timeframe={timeframe} output_format={output_format}"
+                )
 
-        # Import here to avoid circular import
-        from basic_memory.mcp.clients import MemoryClient
+                # Resolve memory:// identifier with project-prefix awareness
+                _, resolved_path, _ = await resolve_project_and_path(
+                    client,
+                    url,
+                    active_project.name,
+                    context,
+                )
 
-        # Use typed MemoryClient for API calls
-        memory_client = MemoryClient(client, active_project.external_id)
-        graph = await memory_client.build_context(
-            resolved_path,
-            depth=depth or 1,
-            timeframe=timeframe,
-            page=page,
-            page_size=page_size,
-            max_related=max_related,
-        )
+                # Import here to avoid circular import
+                from basic_memory.mcp.clients import MemoryClient
 
-        if output_format == "text":
-            return _format_context_markdown(graph, active_project.name)
+                # Use typed MemoryClient for API calls
+                memory_client = MemoryClient(client, active_project.external_id)
+                graph = await memory_client.build_context(
+                    resolved_path,
+                    depth=depth or 1,
+                    timeframe=timeframe,
+                    page=page,
+                    page_size=page_size,
+                    max_related=max_related,
+                )
 
-        return graph.model_dump()
+                logger.info(
+                    f"MCP tool response: tool=build_context project={active_project.name} "
+                    f"uri={graph.metadata.uri or resolved_path} "
+                    f"primary_count={graph.metadata.primary_count or 0} "
+                    f"related_count={graph.metadata.related_count or 0} "
+                    f"output_format={output_format}"
+                )
+
+                if output_format == "text":
+                    return _format_context_markdown(graph, active_project.name)
+
+                return graph.model_dump()

src/basic_memory/mcp/tools/canvas.py

@@ -4,12 +4,14 @@ This tool creates Obsidian canvas files (.canvas) using the JSON Canvas 1.0 spec
 """
 
 import json
-from typing import Dict, List, Any, Optional
+from typing import Annotated, Dict, List, Any, Optional
 
 from loguru import logger
 from fastmcp import Context
+from pydantic import BeforeValidator
 
 from basic_memory.mcp.project_context import get_project_client
+from basic_memory.utils import coerce_list
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_put, call_post, resolve_entity_id
 
@@ -19,8 +21,8 @@ from basic_memory.mcp.tools.utils import call_put, call_post, resolve_entity_id
     annotations={"destructiveHint": False, "idempotentHint": True, "openWorldHint": False},
 )
 async def canvas(
-    nodes: List[Dict[str, Any]],
-    edges: List[Dict[str, Any]],
+    nodes: Annotated[List[Dict[str, Any]], BeforeValidator(coerce_list)],
+    edges: Annotated[List[Dict[str, Any]], BeforeValidator(coerce_list)],
     title: str,
     directory: str,
     project: Optional[str] = None,

src/basic_memory/mcp/tools/delete_note.py

@@ -5,7 +5,8 @@ from loguru import logger
 from fastmcp import Context
 from mcp.server.fastmcp.exceptions import ToolError
 
-from basic_memory.mcp.project_context import get_project_client
+from basic_memory.config import ConfigManager
+from basic_memory.mcp.project_context import detect_project_from_url_prefix, get_project_client
 from basic_memory.mcp.server import mcp
 
 
@@ -222,6 +223,16 @@ async def delete_note(
         with suggestions for finding the correct identifier, including search
         commands and alternative formats to try.
     """
+    # Detect project from memory URL prefix before routing
+    # Trigger: identifier starts with memory:// and no explicit project was provided
+    # Why: only gate on memory:// to avoid misrouting plain paths like "research/note"
+    #      where "research" is a directory, not a project name
+    # Outcome: project is set from the URL prefix, routing goes to the correct project
+    if project is None and identifier.strip().startswith("memory://"):
+        detected = detect_project_from_url_prefix(identifier, ConfigManager().config)
+        if detected:
+            project = detected
+
     async with get_project_client(project, workspace, context) as (client, active_project):
         logger.debug(
             f"Deleting {'directory' if is_directory else 'note'}: {identifier} in project: {active_project.name}"
@@ -318,7 +329,7 @@ delete_note("path/to/file.md")
         note_file_path = None
         try:
             # Resolve identifier to entity ID
-            entity_id = await knowledge_client.resolve_entity(identifier)
+            entity_id = await knowledge_client.resolve_entity(identifier, strict=True)
             if output_format == "json":
                 entity = await knowledge_client.get_entity(entity_id)
                 note_title = entity.title

src/basic_memory/mcp/tools/edit_note.py

@@ -5,7 +5,13 @@ from typing import Optional, Literal
 from loguru import logger
 from fastmcp import Context
 
-from basic_memory.mcp.project_context import get_project_client, add_project_metadata
+from basic_memory.config import ConfigManager
+from basic_memory import telemetry
+from basic_memory.mcp.project_context import (
+    detect_project_from_url_prefix,
+    get_project_client,
+    add_project_metadata,
+)
 from basic_memory.mcp.server import mcp
 from basic_memory.schemas.base import Entity
 from basic_memory.schemas.response import EntityResponse
@@ -158,7 +164,7 @@ Error editing note '{identifier}': {error_message}
 
 
 @mcp.tool(
-    description="Edit an existing markdown note using various operations like append, prepend, find_replace, or replace_section.",
+    description="Edit an existing markdown note using various operations like append, prepend, find_replace, replace_section, insert_before_section, or insert_after_section.",
     annotations={"destructiveHint": False, "openWorldHint": False},
 )
 async def edit_note(
@@ -190,6 +196,8 @@ async def edit_note(
                   - "prepend": Add content to the beginning of the note (creates the note if it doesn't exist)
                   - "find_replace": Replace occurrences of find_text with content (note must exist)
                   - "replace_section": Replace content under a specific markdown header (note must exist)
+                  - "insert_before_section": Insert content before a section heading without consuming it (note must exist)
+                  - "insert_after_section": Insert content after a section heading without consuming it (note must exist)
         content: The content to add or use for replacement
         project: Project name to edit in. Optional - server will resolve using hierarchy.
                 If unknown, use list_memory_projects() to discover available projects.
@@ -253,206 +261,253 @@ async def edit_note(
     # Resolve effective default: allow MCP clients to send null for optional int field
     effective_replacements = expected_replacements if expected_replacements is not None else 1
 
-    async with get_project_client(project, workspace, context) as (client, active_project):
-        logger.info("MCP tool call", tool="edit_note", identifier=identifier, operation=operation)
+    # Detect project from memory URL prefix before routing
+    # Trigger: identifier starts with memory:// and no explicit project was provided
+    # Why: only gate on memory:// to avoid misrouting plain paths like "research/note"
+    #      where "research" is a directory, not a project name
+    # Outcome: project is set from the URL prefix, routing goes to the correct project
+    if project is None and identifier.strip().startswith("memory://"):
+        detected = detect_project_from_url_prefix(identifier, ConfigManager().config)
+        if detected:
+            project = detected
 
-        # Validate operation
-        valid_operations = ["append", "prepend", "find_replace", "replace_section"]
-        if operation not in valid_operations:
-            raise ValueError(
-                f"Invalid operation '{operation}'. Must be one of: {', '.join(valid_operations)}"
-            )
+    with telemetry.operation(
+        "mcp.tool.edit_note",
+        entrypoint="mcp",
+        tool_name="edit_note",
+        requested_project=project,
+        workspace_id=workspace,
+        edit_operation=operation,
+        output_format=output_format,
+        has_section=bool(section),
+        has_find_text=bool(find_text),
+        expected_replacements=effective_replacements,
+    ):
+        async with get_project_client(project, workspace, context) as (client, active_project):
+            with telemetry.contextualize(
+                project_name=active_project.name,
+                workspace_id=workspace,
+                tool_name="edit_note",
+            ):
+                logger.info(
+                    f"MCP tool call tool=edit_note project={active_project.name} "
+                    f"identifier={identifier} operation={operation} output_format={output_format}"
+                )
 
-        # Validate required parameters for specific operations
-        if operation == "find_replace" and not find_text:
-            raise ValueError("find_text parameter is required for find_replace operation")
-        if operation == "replace_section" and not section:
-            raise ValueError("section parameter is required for replace_section operation")
-
-        # Use the PATCH endpoint to edit the entity
-        try:
-            # Import here to avoid circular import
-            from basic_memory.mcp.clients import KnowledgeClient
-
-            # Use typed KnowledgeClient for API calls
-            knowledge_client = KnowledgeClient(client, active_project.external_id)
-
-            file_created = False
-            entity_id = ""
-            result: EntityResponse | None = None
-
-            # Try to resolve the entity; for append/prepend, create it if not found
-            try:
-                entity_id = await knowledge_client.resolve_entity(identifier)
-            except Exception as resolve_error:
-                # Trigger: entity does not exist yet
-                # Why: append/prepend can meaningfully create a new note from the content,
-                #      while find_replace/replace_section require existing content to modify
-                # Outcome: note is created via the same path as write_note
-                error_msg = str(resolve_error).lower()
-                is_not_found = "entity not found" in error_msg or "not found" in error_msg
-
-                if is_not_found and operation in ("append", "prepend"):
-                    title, directory = _parse_identifier_to_title_and_directory(identifier)
-
-                    # Validate directory path (same security check as write_note)
-                    project_path = active_project.home
-                    if directory and not validate_project_path(directory, project_path):
-                        logger.warning(
-                            "Attempted path traversal attack blocked",
-                            directory=directory,
-                            project=active_project.name,
-                        )
-                        if output_format == "json":
-                            return {
-                                "title": title,
-                                "permalink": None,
-                                "file_path": None,
-                                "checksum": None,
-                                "operation": operation,
-                                "fileCreated": False,
-                                "error": "SECURITY_VALIDATION_ERROR",
-                            }
-                        return f"# Error\n\nDirectory path '{directory}' is not allowed - paths must stay within project boundaries"
-
-                    entity = Entity(
-                        title=title,
-                        directory=directory,
-                        content_type="text/markdown",
-                        content=content,
+                # Validate operation
+                valid_operations = [
+                    "append",
+                    "prepend",
+                    "find_replace",
+                    "replace_section",
+                    "insert_before_section",
+                    "insert_after_section",
+                ]
+                if operation not in valid_operations:
+                    raise ValueError(
+                        f"Invalid operation '{operation}'. Must be one of: {', '.join(valid_operations)}"
                     )
 
+                # Validate required parameters for specific operations
+                if operation == "find_replace" and not find_text:
+                    raise ValueError("find_text parameter is required for find_replace operation")
+                section_ops = ("replace_section", "insert_before_section", "insert_after_section")
+                if operation in section_ops and not section:
+                    raise ValueError("section parameter is required for section-based operations")
+
+                # Use the PATCH endpoint to edit the entity
+                try:
+                    # Import here to avoid circular import
+                    from basic_memory.mcp.clients import KnowledgeClient
+
+                    # Use typed KnowledgeClient for API calls
+                    knowledge_client = KnowledgeClient(client, active_project.external_id)
+
+                    file_created = False
+                    entity_id = ""
+                    result: EntityResponse | None = None
+
+                    # Try to resolve the entity; for append/prepend, create it if not found
+                    try:
+                        entity_id = await knowledge_client.resolve_entity(identifier, strict=True)
+                    except Exception as resolve_error:
+                        # Trigger: entity does not exist yet
+                        # Why: append/prepend can meaningfully create a new note from the content,
+                        #      while find_replace/replace_section require existing content to modify
+                        # Outcome: note is created via the same path as write_note
+                        error_msg = str(resolve_error).lower()
+                        is_not_found = "entity not found" in error_msg or "not found" in error_msg
+
+                        if is_not_found and operation in ("append", "prepend"):
+                            title, directory = _parse_identifier_to_title_and_directory(identifier)
+
+                            # Validate directory path (same security check as write_note)
+                            project_path = active_project.home
+                            if directory and not validate_project_path(directory, project_path):
+                                logger.warning(
+                                    "Attempted path traversal attack blocked",
+                                    directory=directory,
+                                    project=active_project.name,
+                                )
+                                if output_format == "json":
+                                    return {
+                                        "title": title,
+                                        "permalink": None,
+                                        "file_path": None,
+                                        "checksum": None,
+                                        "operation": operation,
+                                        "fileCreated": False,
+                                        "error": "SECURITY_VALIDATION_ERROR",
+                                    }
+                                return f"# Error\n\nDirectory path '{directory}' is not allowed - paths must stay within project boundaries"
+
+                            entity = Entity(
+                                title=title,
+                                directory=directory,
+                                content_type="text/markdown",
+                                content=content,
+                            )
+
+                            logger.info(
+                                "Creating note via edit_note auto-create",
+                                title=title,
+                                directory=directory,
+                                operation=operation,
+                            )
+                            result = await knowledge_client.create_entity(
+                                entity.model_dump(), fast=False
+                            )
+                            file_created = True
+                        else:
+                            # find_replace/replace_section require existing content — re-raise
+                            raise resolve_error
+
+                    # --- Standard edit path (entity already existed) ---
+                    if not file_created:
+                        # Prepare the edit request data
+                        edit_data = {
+                            "operation": operation,
+                            "content": content,
+                        }
+
+                        # Add optional parameters
+                        if section:
+                            edit_data["section"] = section
+                        if find_text:
+                            edit_data["find_text"] = find_text
+                        if effective_replacements != 1:  # Only send if different from default
+                            edit_data["expected_replacements"] = str(effective_replacements)
+
+                        # Call the PATCH endpoint
+                        result = await knowledge_client.patch_entity(
+                            entity_id, edit_data, fast=False
+                        )
+
+                    # --- Format response ---
+                    # result is always set: either by create_entity (auto-create) or patch_entity (edit)
+                    assert result is not None
+                    if file_created:
+                        summary = [
+                            f"# Created note ({operation})",
+                            f"project: {active_project.name}",
+                            f"file_path: {result.file_path}",
+                            f"permalink: {result.permalink}",
+                            f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
+                            "fileCreated: true",
+                        ]
+                        lines_added = len(content.split("\n"))
+                        summary.append(f"operation: Created note with {lines_added} lines")
+                    else:
+                        summary = [
+                            f"# Edited note ({operation})",
+                            f"project: {active_project.name}",
+                            f"file_path: {result.file_path}",
+                            f"permalink: {result.permalink}",
+                            f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
+                        ]
+
+                        # Add operation-specific details
+                        if operation == "append":
+                            lines_added = len(content.split("\n"))
+                            summary.append(f"operation: Added {lines_added} lines to end of note")
+                        elif operation == "prepend":
+                            lines_added = len(content.split("\n"))
+                            summary.append(
+                                f"operation: Added {lines_added} lines to beginning of note"
+                            )
+                        elif operation == "find_replace":
+                            # For find_replace, we can't easily count replacements from here
+                            # since we don't have the original content, but the server handled it
+                            summary.append("operation: Find and replace operation completed")
+                        elif operation == "replace_section":
+                            summary.append(f"operation: Replaced content under section '{section}'")
+                        elif operation == "insert_before_section":
+                            summary.append(
+                                f"operation: Inserted content before section '{section}'"
+                            )
+                        elif operation == "insert_after_section":
+                            summary.append(f"operation: Inserted content after section '{section}'")
+
+                    # Count observations by category (reuse logic from write_note)
+                    categories = {}
+                    if result.observations:
+                        for obs in result.observations:
+                            categories[obs.category] = categories.get(obs.category, 0) + 1
+
+                        summary.append("\n## Observations")
+                        for category, count in sorted(categories.items()):
+                            summary.append(f"- {category}: {count}")
+
+                    # Count resolved/unresolved relations
+                    unresolved = 0
+                    resolved = 0
+                    if result.relations:
+                        unresolved = sum(1 for r in result.relations if not r.to_id)
+                        resolved = len(result.relations) - unresolved
+
+                        summary.append("\n## Relations")
+                        summary.append(f"- Resolved: {resolved}")
+                        if unresolved:
+                            summary.append(f"- Unresolved: {unresolved}")
+
                     logger.info(
-                        "Creating note via edit_note auto-create",
-                        title=title,
-                        directory=directory,
-                        operation=operation,
+                        f"MCP tool response: tool=edit_note project={active_project.name} "
+                        f"operation={operation} permalink={result.permalink} "
+                        f"observations_count={len(result.observations)} "
+                        f"relations_count={len(result.relations)} "
+                        f"file_created={str(file_created).lower()}"
                     )
-                    result = await knowledge_client.create_entity(entity.model_dump(), fast=False)
-                    file_created = True
-                else:
-                    # find_replace/replace_section require existing content — re-raise
-                    raise resolve_error
 
-            # --- Standard edit path (entity already existed) ---
-            if not file_created:
-                # Prepare the edit request data
-                edit_data = {
-                    "operation": operation,
-                    "content": content,
-                }
+                    if output_format == "json":
+                        return {
+                            "title": result.title,
+                            "permalink": result.permalink,
+                            "file_path": result.file_path,
+                            "checksum": result.checksum,
+                            "operation": operation,
+                            "fileCreated": file_created,
+                        }
 
-                # Add optional parameters
-                if section:
-                    edit_data["section"] = section
-                if find_text:
-                    edit_data["find_text"] = find_text
-                if effective_replacements != 1:  # Only send if different from default
-                    edit_data["expected_replacements"] = str(effective_replacements)
+                    summary_result = "\n".join(summary)
+                    return add_project_metadata(summary_result, active_project.name)
 
-                # Call the PATCH endpoint
-                result = await knowledge_client.patch_entity(entity_id, edit_data, fast=False)
-
-            # --- Format response ---
-            # result is always set: either by create_entity (auto-create) or patch_entity (edit)
-            assert result is not None
-            if file_created:
-                summary = [
-                    f"# Created note ({operation})",
-                    f"project: {active_project.name}",
-                    f"file_path: {result.file_path}",
-                    f"permalink: {result.permalink}",
-                    f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
-                    "fileCreated: true",
-                ]
-                lines_added = len(content.split("\n"))
-                summary.append(f"operation: Created note with {lines_added} lines")
-            else:
-                summary = [
-                    f"# Edited note ({operation})",
-                    f"project: {active_project.name}",
-                    f"file_path: {result.file_path}",
-                    f"permalink: {result.permalink}",
-                    f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
-                ]
-
-                # Add operation-specific details
-                if operation == "append":
-                    lines_added = len(content.split("\n"))
-                    summary.append(f"operation: Added {lines_added} lines to end of note")
-                elif operation == "prepend":
-                    lines_added = len(content.split("\n"))
-                    summary.append(f"operation: Added {lines_added} lines to beginning of note")
-                elif operation == "find_replace":
-                    # For find_replace, we can't easily count replacements from here
-                    # since we don't have the original content, but the server handled it
-                    summary.append("operation: Find and replace operation completed")
-                elif operation == "replace_section":
-                    summary.append(f"operation: Replaced content under section '{section}'")
-
-            # Count observations by category (reuse logic from write_note)
-            categories = {}
-            if result.observations:
-                for obs in result.observations:
-                    categories[obs.category] = categories.get(obs.category, 0) + 1
-
-                summary.append("\n## Observations")
-                for category, count in sorted(categories.items()):
-                    summary.append(f"- {category}: {count}")
-
-            # Count resolved/unresolved relations
-            unresolved = 0
-            resolved = 0
-            if result.relations:
-                unresolved = sum(1 for r in result.relations if not r.to_id)
-                resolved = len(result.relations) - unresolved
-
-                summary.append("\n## Relations")
-                summary.append(f"- Resolved: {resolved}")
-                if unresolved:
-                    summary.append(f"- Unresolved: {unresolved}")
-
-            logger.info(
-                "MCP tool response",
-                tool="edit_note",
-                operation=operation,
-                project=active_project.name,
-                permalink=result.permalink,
-                observations_count=len(result.observations),
-                relations_count=len(result.relations),
-                file_created=file_created,
-            )
-
-            if output_format == "json":
-                return {
-                    "title": result.title,
-                    "permalink": result.permalink,
-                    "file_path": result.file_path,
-                    "checksum": result.checksum,
-                    "operation": operation,
-                    "fileCreated": file_created,
-                }
-
-            summary_result = "\n".join(summary)
-            return add_project_metadata(summary_result, active_project.name)
-
-        except Exception as e:
-            logger.error(f"Error editing note: {e}")
-            if output_format == "json":
-                return {
-                    "title": None,
-                    "permalink": None,
-                    "file_path": None,
-                    "checksum": None,
-                    "operation": operation,
-                    "fileCreated": False,
-                    "error": str(e),
-                }
-            return _format_error_response(
-                str(e),
-                operation,
-                identifier,
-                find_text,
-                effective_replacements,
-                active_project.name,
-            )
+                except Exception as e:
+                    logger.error(f"Error editing note: {e}")
+                    if output_format == "json":
+                        return {
+                            "title": None,
+                            "permalink": None,
+                            "file_path": None,
+                            "checksum": None,
+                            "operation": operation,
+                            "fileCreated": False,
+                            "error": str(e),
+                        }
+                    return _format_error_response(
+                        str(e),
+                        operation,
+                        identifier,
+                        find_text,
+                        effective_replacements,
+                        active_project.name,
+                    )

src/basic_memory/mcp/tools/move_note.py

@@ -6,6 +6,7 @@ from typing import Optional, Literal
 
 from loguru import logger
 from fastmcp import Context
+from mcp.server.fastmcp.exceptions import ToolError
 
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.project_context import get_project_client
@@ -476,8 +477,11 @@ async def move_note(
             }
         return f"# Move Failed - Invalid Parameters\n\n{error_msg}"
     async with get_project_client(project, workspace, context) as (client, active_project):
-        logger.debug(
-            f"Moving {'directory' if is_directory else 'note'}: {identifier} to {destination_path} in project: {active_project.name}"
+        destination_target = destination_folder or destination_path
+        logger.info(
+            f"MCP tool call tool=move_note project={active_project.name} "
+            f"identifier={identifier} destination={destination_target} "
+            f"is_directory={str(is_directory).lower()}"
         )
 
         # Validate destination path to prevent path traversal attacks
@@ -637,7 +641,7 @@ move_note("path/to/file.md", "{destination_path}/file.md")
             """Resolve and cache the source entity ID for the duration of this move."""
             nonlocal resolved_entity_id
             if resolved_entity_id is None:
-                resolved_entity_id = await knowledge_client.resolve_entity(identifier)
+                resolved_entity_id = await knowledge_client.resolve_entity(identifier, strict=True)
             return resolved_entity_id
 
         try:
@@ -645,8 +649,26 @@ move_note("path/to/file.md", "{destination_path}/file.md")
             source_entity = await knowledge_client.get_entity(resolved_entity_id)
             if "." in source_entity.file_path:
                 source_ext = source_entity.file_path.split(".")[-1]
+        except ToolError as e:
+            # Trigger: strict=True resolve_entity raised because the entity was not found.
+            # Why: fail fast with a formatted error instead of silently falling through
+            #      to extension defaults and failing later with a confusing message.
+            # Outcome: move_note returns a user-facing not-found error immediately.
+            logger.error(f"Move failed for '{identifier}' to '{destination_path}': {e}")
+            if output_format == "json":
+                return {
+                    "moved": False,
+                    "title": None,
+                    "permalink": None,
+                    "file_path": None,
+                    "source": identifier,
+                    "destination": destination_path,
+                    "error": str(e),
+                }
+            return _format_move_error_response(str(e), identifier, destination_path)
         except Exception as e:
-            # If we can't fetch source metadata, continue with extension defaults.
+            # If we can't fetch source metadata (e.g. get_entity or file_path parsing fails),
+            # continue with extension defaults — the entity was at least resolved.
             logger.debug(f"Could not fetch source entity for extension check: {e}")
 
         # --- Resolve destination_folder into destination_path ---
@@ -815,10 +837,8 @@ move_note("{identifier}", destination_folder="notes")
 
             # Log the operation
             logger.info(
-                "Move note completed",
-                identifier=identifier,
-                destination_path=destination_path,
-                project=active_project.name,
+                f"MCP tool response: tool=move_note project={active_project.name} "
+                f"source={identifier} destination={result.file_path} permalink={result.permalink}"
             )
 
             return "\n".join(result_lines)

src/basic_memory/mcp/tools/read_content.py

@@ -216,7 +216,7 @@ async def read_content(
         if detected:
             project = detected
 
-    logger.info("Reading file", path=path, project=project)
+    logger.info(f"MCP tool call tool=read_content project={project} path={path}")
 
     async with get_project_client(project, workspace, context) as (client, active_project):
         # Resolve path with project-prefix awareness for memory:// URLs
@@ -260,6 +260,10 @@ async def read_content(
         # Handle text or json
         if content_type.startswith("text/") or content_type == "application/json":
             logger.debug("Processing text resource")
+            logger.info(
+                f"MCP tool response: tool=read_content project={active_project.name} "
+                f"path={url} type=text content_type={content_type}"
+            )
             return {
                 "type": "text",
                 "text": response.text,
@@ -272,6 +276,10 @@ async def read_content(
             logger.debug("Processing image")
             img = PILImage.open(io.BytesIO(response.content))
             img_bytes = optimize_image(img, content_length)
+            logger.info(
+                f"MCP tool response: tool=read_content project={active_project.name} "
+                f"path={url} type=image content_type=image/jpeg"
+            )
 
             return {
                 "type": "image",
@@ -291,6 +299,10 @@ async def read_content(
                     "type": "error",
                     "error": f"Document size {content_length} bytes exceeds maximum allowed size",
                 }
+            logger.info(
+                f"MCP tool response: tool=read_content project={active_project.name} "
+                f"path={url} type=document content_type={content_type}"
+            )
             return {
                 "type": "document",
                 "source": {

src/basic_memory/mcp/tools/read_note.py

@@ -1,13 +1,14 @@
 """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
 
 from loguru import logger
 from fastmcp import Context
 
+from basic_memory import telemetry
 from basic_memory.config import ConfigManager
 from basic_memory.mcp.project_context import (
     detect_project_from_url_prefix,
@@ -139,186 +140,233 @@ async def read_note(
         if detected:
             project = detected
 
-    async with get_project_client(project, workspace, context) as (client, active_project):
-        # Resolve identifier with project-prefix awareness for memory:// URLs
-        _, entity_path, _ = await resolve_project_and_path(client, identifier, project, context)
+    with telemetry.operation(
+        "mcp.tool.read_note",
+        entrypoint="mcp",
+        tool_name="read_note",
+        requested_project=project,
+        workspace_id=workspace,
+        output_format=output_format,
+        page=page,
+        page_size=page_size,
+        include_frontmatter=include_frontmatter,
+    ):
+        async with get_project_client(project, workspace, context) as (client, active_project):
+            with telemetry.contextualize(
+                project_name=active_project.name,
+                workspace_id=workspace,
+                tool_name="read_note",
+            ):
+                # Resolve identifier with project-prefix awareness for memory:// URLs
+                _, entity_path, _ = await resolve_project_and_path(
+                    client, identifier, project, context
+                )
 
-        # Validate identifier to prevent path traversal attacks
-        # For memory:// URLs, validate the extracted path (not the raw URL which
-        # has a scheme prefix that confuses path validation)
-        raw_path = memory_url_path(identifier) if identifier.startswith("memory://") else identifier
-        processed_path = entity_path
-        project_path = active_project.home
+                # Validate identifier to prevent path traversal attacks
+                # For memory:// URLs, validate the extracted path (not the raw URL which
+                # has a scheme prefix that confuses path validation)
+                raw_path = (
+                    memory_url_path(identifier)
+                    if identifier.startswith("memory://")
+                    else identifier
+                )
+                processed_path = entity_path
+                project_path = active_project.home
 
-        if not validate_project_path(raw_path, project_path) or not validate_project_path(
-            processed_path, project_path
-        ):
-            logger.warning(
-                "Attempted path traversal attack blocked",
-                identifier=identifier,
-                processed_path=processed_path,
-                project=active_project.name,
-            )
-            if output_format == "json":
-                return {
-                    "title": None,
-                    "permalink": None,
-                    "file_path": None,
-                    "content": None,
-                    "frontmatter": None,
-                    "error": "SECURITY_VALIDATION_ERROR",
-                }
-            return f"# Error\n\nIdentifier '{identifier}' is not allowed - paths must stay within project boundaries"
-
-        # Get the file via REST API - first try direct identifier resolution
-        logger.info(
-            f"Attempting to read note from Project: {active_project.name} identifier: {entity_path}"
-        )
-
-        # Import here to avoid circular import
-        from basic_memory.mcp.clients import KnowledgeClient, ResourceClient
-
-        # Use typed clients for API calls
-        knowledge_client = KnowledgeClient(client, active_project.external_id)
-        resource_client = ResourceClient(client, active_project.external_id)
-
-        async def _read_json_payload(entity_id: str) -> dict:
-            entity = await knowledge_client.get_entity(entity_id)
-            response = await resource_client.read(entity_id, page=page, page_size=page_size)
-            content_text = response.text
-            body_content, parsed_frontmatter = _parse_opening_frontmatter(content_text)
-            return {
-                "title": entity.title,
-                "permalink": entity.permalink,
-                "file_path": entity.file_path,
-                "content": content_text if include_frontmatter else body_content,
-                "frontmatter": parsed_frontmatter,
-            }
-
-        def _empty_json_payload() -> dict:
-            return {
-                "title": None,
-                "permalink": None,
-                "file_path": None,
-                "content": None,
-                "frontmatter": None,
-            }
-
-        def _search_results(payload: object) -> list[dict]:
-            if not isinstance(payload, dict):
-                return []
-            results = payload.get("results")
-            return results if isinstance(results, list) else []
-
-        def _result_title(item: dict) -> str:
-            return str(item.get("title") or "")
-
-        def _result_permalink(item: dict) -> Optional[str]:
-            value = item.get("permalink")
-            return str(value) if value else None
-
-        def _result_file_path(item: dict) -> Optional[str]:
-            value = item.get("file_path")
-            return str(value) if value else None
-
-        try:
-            # Try to resolve identifier to entity ID
-            entity_id = await knowledge_client.resolve_entity(entity_path, strict=True)
-
-            # Fetch content using entity ID
-            response = await resource_client.read(entity_id, page=page, page_size=page_size)
-
-            # If successful, return the content
-            if response.status_code == 200:
-                logger.info("Returning read_note result from resource: {path}", path=entity_path)
-                if output_format == "json":
-                    return await _read_json_payload(entity_id)
-                return response.text
-        except Exception as e:  # pragma: no cover
-            logger.info(f"Direct lookup failed for '{entity_path}': {e}")
-            # Continue to fallback methods
-
-        # Fallback 1: Try title search via API
-        logger.info(f"Search title for: {identifier}")
-        title_results = await search_notes(
-            query=identifier,
-            search_type="title",
-            project=active_project.name,
-            workspace=workspace,
-            output_format="json",
-            context=context,
-        )
-
-        title_candidates = _search_results(title_results)
-        if title_candidates:
-            # Trigger: direct resolution failed and title search returned candidates.
-            # Why: avoid returning unrelated notes when search yields only fuzzy matches.
-            # Outcome: fetch content only when a true exact title match exists.
-            result = next(
-                (
-                    candidate
-                    for candidate in title_candidates
-                    if _is_exact_title_match(identifier, _result_title(candidate))
-                ),
-                None,
-            )
-            if not result:
-                logger.info(f"No exact title match found for: {identifier}")
-            elif _result_permalink(result):
-                try:
-                    # Resolve the permalink to entity ID
-                    entity_id = await knowledge_client.resolve_entity(
-                        _result_permalink(result) or "", strict=True
+                if not validate_project_path(raw_path, project_path) or not validate_project_path(
+                    processed_path, project_path
+                ):
+                    logger.warning(
+                        "Attempted path traversal attack blocked",
+                        identifier=identifier,
+                        processed_path=processed_path,
+                        project=active_project.name,
                     )
+                    if output_format == "json":
+                        return {
+                            "title": None,
+                            "permalink": None,
+                            "file_path": None,
+                            "content": None,
+                            "frontmatter": None,
+                            "error": "SECURITY_VALIDATION_ERROR",
+                        }
+                    return f"# Error\n\nIdentifier '{identifier}' is not allowed - paths must stay within project boundaries"
 
-                    # Fetch content using the entity ID
+                # Get the file via REST API - first try direct identifier resolution
+                logger.info(
+                    f"Attempting to read note from Project: {active_project.name} identifier: {entity_path}"
+                )
+
+                # Import here to avoid circular import
+                from basic_memory.mcp.clients import KnowledgeClient, ResourceClient
+
+                # Use typed clients for API calls
+                knowledge_client = KnowledgeClient(client, active_project.external_id)
+                resource_client = ResourceClient(client, active_project.external_id)
+
+                async def _read_json_payload(entity_id: str) -> dict:
+                    with telemetry.scope(
+                        "mcp.read_note.shape_response",
+                        domain="mcp",
+                        action="read_note",
+                        phase="shape_response",
+                    ):
+                        entity = await knowledge_client.get_entity(entity_id)
+                        response = await resource_client.read(
+                            entity_id, page=page, page_size=page_size
+                        )
+                        content_text = response.text
+                        body_content, parsed_frontmatter = _parse_opening_frontmatter(content_text)
+                        return {
+                            "title": entity.title,
+                            "permalink": entity.permalink,
+                            "file_path": entity.file_path,
+                            "content": content_text if include_frontmatter else body_content,
+                            "frontmatter": parsed_frontmatter,
+                        }
+
+                def _empty_json_payload() -> dict:
+                    return {
+                        "title": None,
+                        "permalink": None,
+                        "file_path": None,
+                        "content": None,
+                        "frontmatter": None,
+                    }
+
+                def _search_results(payload: object) -> list[dict[str, object]]:
+                    if not isinstance(payload, dict):
+                        return []
+                    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[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.
+                    # Outcome: unresolved memory URLs still fall back through normalized search.
+                    search_type = "title" if title_only else "text"
+                    response = await search_notes(
+                        project=active_project.name,
+                        workspace=workspace,
+                        query=identifier_text,
+                        search_type=search_type,
+                        page=page,
+                        page_size=page_size,
+                        output_format="json",
+                        context=context,
+                    )
+                    return cast(dict[str, object], response) if isinstance(response, dict) else {}
+
+                def _result_title(item: dict[str, object]) -> str:
+                    return str(item.get("title") or "")
+
+                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[str, object]) -> Optional[str]:
+                    value = item.get("file_path")
+                    return str(value) if value else None
+
+                try:
+                    # Try to resolve identifier to entity ID
+                    entity_id = await knowledge_client.resolve_entity(entity_path, strict=True)
+
+                    # Fetch content using entity ID
                     response = await resource_client.read(entity_id, page=page, page_size=page_size)
 
+                    # If successful, return the content
                     if response.status_code == 200:
                         logger.info(
-                            f"Found note by exact title search: {_result_permalink(result)}"
+                            "Returning read_note result from resource: {path}", path=entity_path
                         )
                         if output_format == "json":
                             return await _read_json_payload(entity_id)
                         return response.text
                 except Exception as e:  # pragma: no cover
-                    logger.info(
-                        f"Failed to fetch content for found title match {_result_permalink(result)}: {e}"
+                    logger.info(f"Direct lookup failed for '{entity_path}': {e}")
+                    # Continue to fallback methods
+
+                # Fallback 1: Try title search via API
+                logger.info(f"Search title for: {identifier}")
+                title_results = await _search_candidates(identifier, title_only=True)
+
+                title_candidates = _search_results(title_results)
+                if title_candidates:
+                    # Trigger: direct resolution failed and title search returned candidates.
+                    # Why: avoid returning unrelated notes when search yields only fuzzy matches.
+                    # Outcome: fetch content only when a true exact title match exists.
+                    result = next(
+                        (
+                            candidate
+                            for candidate in title_candidates
+                            if _is_exact_title_match(identifier, _result_title(candidate))
+                        ),
+                        None,
                     )
-        else:
-            logger.info(
-                f"No results in title search for: {identifier} in project {active_project.name}"
-            )
+                    if not result:
+                        logger.info(f"No exact title match found for: {identifier}")
+                    elif _result_permalink(result):
+                        try:
+                            # Resolve the permalink to entity ID
+                            entity_id = await knowledge_client.resolve_entity(
+                                _result_permalink(result) or "", strict=True
+                            )
 
-        # Fallback 2: Text search as a last resort
-        logger.info(f"Title search failed, trying text search for: {identifier}")
-        text_results = await search_notes(
-            query=identifier,
-            search_type="text",
-            project=active_project.name,
-            workspace=workspace,
-            output_format="json",
-            context=context,
-        )
+                            # Fetch content using the entity ID
+                            response = await resource_client.read(
+                                entity_id, page=page, page_size=page_size
+                            )
 
-        # We didn't find a direct match, construct a helpful error message
-        text_candidates = _search_results(text_results)
-        if not text_candidates:
-            if output_format == "json":
-                return _empty_json_payload()
-            return format_not_found_message(active_project.name, identifier)
-        if output_format == "json":
-            payload = _empty_json_payload()
-            payload["related_results"] = [
-                {
-                    "title": _result_title(result),
-                    "permalink": _result_permalink(result),
-                    "file_path": _result_file_path(result),
-                }
-                for result in text_candidates[:5]
-            ]
-            return payload
-        return format_related_results(active_project.name, identifier, text_candidates[:5])
+                            if response.status_code == 200:
+                                logger.info(
+                                    f"Found note by exact title search: {_result_permalink(result)}"
+                                )
+                                if output_format == "json":
+                                    return await _read_json_payload(entity_id)
+                                return response.text
+                        except Exception as e:  # pragma: no cover
+                            logger.info(
+                                f"Failed to fetch content for found title match {_result_permalink(result)}: {e}"
+                            )
+                else:
+                    logger.info(
+                        f"No results in title search for: {identifier} in project {active_project.name}"
+                    )
+
+                # Fallback 2: Text search as a last resort
+                logger.info(f"Title search failed, trying text search for: {identifier}")
+                text_results = await _search_candidates(identifier, title_only=False)
+
+                # We didn't find a direct match, construct a helpful error message
+                text_candidates = _search_results(text_results)
+                if not text_candidates:
+                    if output_format == "json":
+                        return _empty_json_payload()
+                    return format_not_found_message(active_project.name, identifier)
+                if output_format == "json":
+                    payload = _empty_json_payload()
+                    payload["related_results"] = [
+                        {
+                            "title": _result_title(result),
+                            "permalink": _result_permalink(result),
+                            "file_path": _result_file_path(result),
+                        }
+                        for result in text_candidates[:5]
+                    ]
+                    return payload
+                return format_related_results(active_project.name, identifier, text_candidates[:5])
 
 
 def format_not_found_message(project: str | None, identifier: str) -> str:

src/basic_memory/mcp/tools/schema.py

@@ -160,7 +160,7 @@ def _no_notes_guidance(note_type: str, tool_name: str) -> str:
         f"## Next Steps\n\n"
         f"1. **Create notes of this type** — use `write_note` with "
         f'`note_type="{note_type}"` to create notes\n'
-        f"2. **Check existing types** — use `search_notes` with `entity_types` "
+        f"2. **Check existing types** — use `search_notes` with `note_types` "
         f"filter to see what types exist\n"
         f"3. **Browse content** — use `list_directory` or `recent_activity` to "
         f"see what's in the project\n"
@@ -397,7 +397,7 @@ async def schema_infer(
                     f"share a consistent structure.\n\n"
                     f"## Suggestions\n"
                     f"1. **Use a more specific type** — try `search_notes` with "
-                    f"`entity_types` filter to see what types exist\n"
+                    f"`note_types` filter to see what types exist\n"
                     f"2. **Lower the threshold** — "
                     f'`schema_infer("{note_type}", threshold=0.1)` to include '
                     f"rarer fields\n"

src/basic_memory/mcp/tools/search.py

@@ -2,12 +2,15 @@
 
 import re
 from textwrap import dedent
-from typing import List, Optional, Dict, Any, Literal
+from typing import Annotated, List, Optional, Dict, Any, Literal
 
 from loguru import logger
 from fastmcp import Context
+from pydantic import BeforeValidator
 
+from basic_memory import telemetry
 from basic_memory.config import ConfigManager
+from basic_memory.utils import coerce_dict, coerce_list
 from basic_memory.mcp.container import get_container
 from basic_memory.mcp.project_context import (
     detect_project_from_url_prefix,
@@ -23,20 +26,20 @@ from basic_memory.schemas.search import (
 )
 
 
-def _semantic_search_enabled_for_text_search() -> bool:
-    """Resolve semantic-search enablement in both MCP and CLI invocation paths."""
-    try:
-        return get_container().config.semantic_search_enabled
-    except RuntimeError:
-        # Trigger: MCP container is not initialized (e.g., `bm tool search-notes` direct call).
-        # Why: CLI path still needs the same semantic-default behavior as MCP server path.
-        # Outcome: load config directly and keep text-mode retrieval behavior consistent.
-        return ConfigManager().config.semantic_search_enabled
-
-
 def _default_search_type() -> str:
-    """Pick default search mode from semantic-search config."""
-    return "hybrid" if _semantic_search_enabled_for_text_search() else "text"
+    """Pick default search mode from config, falling back to auto-detection.
+
+    Priority: config default_search_type > auto-detect (hybrid if semantic enabled, else text).
+    """
+    try:
+        config = get_container().config
+    except RuntimeError:
+        config = ConfigManager().config
+
+    if config.default_search_type:
+        return config.default_search_type
+
+    return "hybrid" if config.semantic_search_enabled else "text"
 
 
 def _format_search_error_response(
@@ -165,7 +168,7 @@ def _format_search_error_response(
                - Remove restrictive terms: Focus on the most important keywords
 
             5. **Use filtering to narrow scope**:
-               - By content type: `search_notes("{project}","{query}", note_types=["note"])`
+               - By note type in frontmatter: `search_notes("{project}","{query}", note_types=["note"])`
                - By recent content: `search_notes("{project}","{query}", after_date="1 week")`
                - By entity type: `search_notes("{project}","{query}", entity_types=["observation"])`
 
@@ -305,11 +308,28 @@ async def search_notes(
     page_size: int = 10,
     search_type: str | None = None,
     output_format: Literal["text", "json"] = "text",
-    note_types: List[str] | None = None,
-    entity_types: List[str] | None = None,
+    note_types: Annotated[
+        List[str] | None,
+        BeforeValidator(coerce_list),
+        "Filter by the 'type' field in note frontmatter (e.g. 'note', 'chapter', 'person'). "
+        "Case-insensitive.",
+    ] = None,
+    entity_types: Annotated[
+        List[str] | None,
+        BeforeValidator(coerce_list),
+        "Filter by knowledge graph item type: 'entity' (whole notes), 'observation', or "
+        "'relation'. Defaults to 'entity'. Do NOT pass schema/frontmatter types like "
+        "'Chapter' here — use note_types instead.",
+    ] = None,
     after_date: Optional[str] = None,
-    metadata_filters: Optional[Dict[str, Any]] = None,
-    tags: Optional[List[str]] = None,
+    metadata_filters: Annotated[
+        Dict[str, Any] | None,
+        BeforeValidator(coerce_dict),
+    ] = None,
+    tags: Annotated[
+        List[str] | None,
+        BeforeValidator(coerce_list),
+    ] = None,
     status: Optional[str] = None,
     min_similarity: Optional[float] = None,
     context: Context | None = None,
@@ -350,6 +370,7 @@ async def search_notes(
     ### Search Type Examples
     - `search_notes("my-project", "Meeting", search_type="title")` - Search only in titles
     - `search_notes("work-docs", "docs/meeting-*", search_type="permalink")` - Pattern match permalinks
+      Note: Permalink patterns match the full path (e.g., "project/folder/chapter-13*", not just "chapter-13*").
     - `search_notes("research", "keyword")` - Default search (hybrid when semantic is enabled,
       text when disabled)
 
@@ -436,7 +457,7 @@ async def search_notes(
         # Exact phrase search
         results = await search_notes("\"weekly standup meeting\"")
 
-        # Search with note type filter
+        # Search with note type filter - type property in frontmatter
         results = await search_notes(
             "meeting notes",
             note_types=["note"],
@@ -477,7 +498,8 @@ async def search_notes(
         results = await search_notes("project planning", project="my-project")
     """
     # Avoid mutable-default-argument footguns. Treat None as "no filter".
-    note_types = note_types or []
+    # Lowercase note_types so "Chapter" matches the stored "chapter".
+    note_types = [t.lower() for t in note_types] if note_types else []
     entity_types = entity_types or []
 
     # Parse tag:<value> shorthand at tool level so it works with all search modes.
@@ -502,124 +524,159 @@ async def search_notes(
         if detected:
             project = detected
 
-    async with get_project_client(project, workspace, context) as (client, active_project):
-        # Handle memory:// URLs by resolving to permalink search
-        is_memory_url = False
-        if query is not None:
-            _, resolved_query, is_memory_url = await resolve_project_and_path(
-                client, query, project, context
-            )
-            if is_memory_url:
-                query = resolved_query
-        effective_search_type = search_type or _default_search_type()
-        if is_memory_url:
-            effective_search_type = "permalink"
+    with telemetry.operation(
+        "mcp.tool.search_notes",
+        entrypoint="mcp",
+        tool_name="search_notes",
+        requested_project=project,
+        workspace_id=workspace,
+        search_type=search_type or "default",
+        output_format=output_format,
+        page=page,
+        page_size=page_size,
+        has_query=bool(query and query.strip()),
+        note_type_filter_count=len(note_types),
+        entity_type_filter_count=len(entity_types),
+        has_filters=bool(
+            metadata_filters or tags or status or note_types or entity_types or after_date
+        ),
+        has_tags_filter=bool(tags),
+        has_status_filter=bool(status),
+    ):
+        async with get_project_client(project, workspace, context) as (client, active_project):
+            with telemetry.contextualize(
+                project_name=active_project.name,
+                workspace_id=workspace,
+                tool_name="search_notes",
+            ):
+                # Handle memory:// URLs by resolving to permalink search
+                is_memory_url = False
+                if query is not None:
+                    _, resolved_query, is_memory_url = await resolve_project_and_path(
+                        client, query, project, context
+                    )
+                    if is_memory_url:
+                        query = resolved_query
+                effective_search_type = search_type or _default_search_type()
+                if is_memory_url:
+                    effective_search_type = "permalink"
 
-        try:
-            # Create a SearchQuery object based on the parameters
-            search_query = SearchQuery()
+                try:
+                    # Create a SearchQuery object based on the parameters
+                    search_query = SearchQuery()
 
-            # Only map search_type to query fields when there is an actual query string.
-            # When query is None/empty, skip the search mode block — filters-only path.
-            effective_query = (query or "").strip()
-            if effective_query:
-                valid_search_types = {
-                    "text",
-                    "title",
-                    "permalink",
-                    "vector",
-                    "semantic",
-                    "hybrid",
-                }
-                if effective_search_type == "text":
-                    search_query.text = effective_query
-                    search_query.retrieval_mode = SearchRetrievalMode.FTS
-                elif effective_search_type in ("vector", "semantic"):
-                    search_query.text = effective_query
-                    search_query.retrieval_mode = SearchRetrievalMode.VECTOR
-                elif effective_search_type == "hybrid":
-                    search_query.text = effective_query
-                    search_query.retrieval_mode = SearchRetrievalMode.HYBRID
-                elif effective_search_type == "title":
-                    search_query.title = effective_query
-                elif effective_search_type == "permalink" and "*" in effective_query:
-                    search_query.permalink_match = effective_query
-                elif effective_search_type == "permalink":
-                    search_query.permalink = effective_query
-                else:
-                    raise ValueError(
-                        f"Invalid search_type '{effective_search_type}'. "
-                        f"Valid options: {', '.join(sorted(valid_search_types))}"
+                    # Only map search_type to query fields when there is an actual query string.
+                    # When query is None/empty, skip the search mode block — filters-only path.
+                    effective_query = (query or "").strip()
+                    if effective_query:
+                        valid_search_types = {
+                            "text",
+                            "title",
+                            "permalink",
+                            "vector",
+                            "semantic",
+                            "hybrid",
+                        }
+                        if effective_search_type == "text":
+                            search_query.text = effective_query
+                            search_query.retrieval_mode = SearchRetrievalMode.FTS
+                        elif effective_search_type in ("vector", "semantic"):
+                            search_query.text = effective_query
+                            search_query.retrieval_mode = SearchRetrievalMode.VECTOR
+                        elif effective_search_type == "hybrid":
+                            search_query.text = effective_query
+                            search_query.retrieval_mode = SearchRetrievalMode.HYBRID
+                        elif effective_search_type == "title":
+                            search_query.title = effective_query
+                        elif effective_search_type == "permalink" and "*" in effective_query:
+                            search_query.permalink_match = effective_query
+                        elif effective_search_type == "permalink":
+                            search_query.permalink = effective_query
+                        else:
+                            raise ValueError(
+                                f"Invalid search_type '{effective_search_type}'. "
+                                f"Valid options: {', '.join(sorted(valid_search_types))}"
+                            )
+
+                    # Add optional filters if provided (empty lists are treated as no filter)
+                    if entity_types:
+                        search_query.entity_types = [SearchItemType(t) for t in entity_types]
+                    if note_types:
+                        search_query.note_types = note_types
+                    if after_date:
+                        search_query.after_date = after_date
+                    if metadata_filters:
+                        # Alias common column/model names to their frontmatter key equivalents.
+                        # Users often pass "note_type" (the entity model column) when the
+                        # frontmatter field is actually "type".
+                        _METADATA_KEY_ALIASES = {"note_type": "type"}
+                        metadata_filters = {
+                            _METADATA_KEY_ALIASES.get(k, k): v for k, v in metadata_filters.items()
+                        }
+                        search_query.metadata_filters = metadata_filters
+                    if tags:
+                        search_query.tags = tags
+                    if status:
+                        search_query.status = status
+                    if min_similarity is not None:
+                        search_query.min_similarity = min_similarity
+
+                    # Reject searches with no criteria at all
+                    if search_query.no_criteria():
+                        return (
+                            "# No Search Criteria\n\n"
+                            "Please provide at least one of: `query`, `metadata_filters`, "
+                            "`tags`, `status`, `note_types`, `entity_types`, or `after_date`."
+                        )
+
+                    # Default to entity-level results to avoid returning individual
+                    # observations/relations as separate search results (see issue #31).
+                    # Applied after no_criteria() so that the implicit default doesn't
+                    # mask a truly empty search request.
+                    if not search_query.entity_types:
+                        search_query.entity_types = [SearchItemType("entity")]
+
+                    logger.debug(
+                        f"Search request: project={active_project.name} "
+                        f"search_type={effective_search_type} "
+                        f"query={effective_query or '<filters-only>'} "
+                        f"note_types={len(note_types)} entity_types={len(search_query.entity_types or [])} "
+                        f"page={page} page_size={page_size}"
+                    )
+                    # Import here to avoid circular import (tools → clients → utils → tools)
+                    from basic_memory.mcp.clients import SearchClient
+
+                    # Use typed SearchClient for API calls
+                    search_client = SearchClient(client, active_project.external_id)
+                    result = await search_client.search(
+                        search_query.model_dump(),
+                        page=page,
+                        page_size=page_size,
+                    )
+                    logger.debug(
+                        f"Search response: project={active_project.name} "
+                        f"results={len(result.results)} has_more={str(result.has_more).lower()} "
+                        f"page={result.current_page} page_size={result.page_size}"
                     )
 
-            # Add optional filters if provided (empty lists are treated as no filter)
-            if entity_types:
-                search_query.entity_types = [SearchItemType(t) for t in entity_types]
-            if note_types:
-                search_query.note_types = note_types
-            if after_date:
-                search_query.after_date = after_date
-            if metadata_filters:
-                # Alias common column/model names to their frontmatter key equivalents.
-                # Users often pass "note_type" (the entity model column) when the
-                # frontmatter field is actually "type".
-                _METADATA_KEY_ALIASES = {"note_type": "type"}
-                metadata_filters = {
-                    _METADATA_KEY_ALIASES.get(k, k): v for k, v in metadata_filters.items()
-                }
-                search_query.metadata_filters = metadata_filters
-            if tags:
-                search_query.tags = tags
-            if status:
-                search_query.status = status
-            if min_similarity is not None:
-                search_query.min_similarity = min_similarity
+                    # Check if we got no results and provide helpful guidance
+                    if not result.results:
+                        logger.debug(
+                            f"Search returned no results for query: {query} in project {active_project.name}"
+                        )
+                        # Don't treat this as an error, but the user might want guidance
+                        # We return the empty result as normal - the user can decide if they need help
 
-            # Reject searches with no criteria at all
-            if search_query.no_criteria():
-                return (
-                    "# No Search Criteria\n\n"
-                    "Please provide at least one of: `query`, `metadata_filters`, "
-                    "`tags`, `status`, `note_types`, `entity_types`, or `after_date`."
-                )
+                    if output_format == "json":
+                        return result.model_dump(mode="json", exclude_none=True)
 
-            # Default to entity-level results to avoid returning individual
-            # observations/relations as separate search results (see issue #31).
-            # Applied after no_criteria() so that the implicit default doesn't
-            # mask a truly empty search request.
-            if not search_query.entity_types:
-                search_query.entity_types = [SearchItemType("entity")]
+                    return _format_search_markdown(result, active_project.name, query)
 
-            logger.debug(f"Searching for {search_query} in project {active_project.name}")
-            # Import here to avoid circular import (tools → clients → utils → tools)
-            from basic_memory.mcp.clients import SearchClient
-
-            # Use typed SearchClient for API calls
-            search_client = SearchClient(client, active_project.external_id)
-            result = await search_client.search(
-                search_query.model_dump(),
-                page=page,
-                page_size=page_size,
-            )
-
-            # Check if we got no results and provide helpful guidance
-            if not result.results:
-                logger.debug(
-                    f"Search returned no results for query: {query} in project {active_project.name}"
-                )
-                # Don't treat this as an error, but the user might want guidance
-                # We return the empty result as normal - the user can decide if they need help
-
-            if output_format == "json":
-                return result.model_dump(mode="json", exclude_none=True)
-
-            return _format_search_markdown(result, active_project.name, query)
-
-        except Exception as e:
-            logger.error(
-                f"Search failed for query '{query or ''}': {e}, project: {active_project.name}"
-            )
-            # Return formatted error message as string for better user experience
-            return _format_search_error_response(
-                active_project.name, str(e), query or "", effective_search_type
-            )
+                except Exception as e:
+                    logger.error(
+                        f"Search failed for query '{query or ''}': {e}, project: {active_project.name}"
+                    )
+                    # Return formatted error message as string for better user experience
+                    return _format_search_error_response(
+                        active_project.name, str(e), query or "", effective_search_type
+                    )

src/basic_memory/mcp/tools/ui_sdk.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict, List, Optional
+from typing import Annotated, Any, Dict, List, Optional
 
 from fastmcp import Context
 from mcp.types import ContentBlock, TextContent
@@ -28,8 +28,17 @@ async def search_notes_ui(
     page: int = 1,
     page_size: int = 10,
     search_type: Optional[str] = None,
-    note_types: List[str] | None = None,
-    entity_types: List[str] | None = None,
+    note_types: Annotated[
+        List[str] | None,
+        "Filter by the 'type' field in note frontmatter (e.g. 'note', 'chapter', 'person'). "
+        "Case-insensitive.",
+    ] = None,
+    entity_types: Annotated[
+        List[str] | None,
+        "Filter by knowledge graph item type: 'entity' (whole notes), 'observation', or "
+        "'relation'. Defaults to 'entity'. Do NOT pass schema/frontmatter types like "
+        "'Chapter' here — use note_types instead.",
+    ] = None,
     after_date: Optional[str] = None,
     metadata_filters: Optional[Dict[str, Any]] = None,
     tags: Optional[List[str]] = None,

src/basic_memory/mcp/tools/utils.py

@@ -5,6 +5,7 @@ to the Basic Memory API, with improved error handling and logging.
 """
 
 import typing
+from contextlib import contextmanager
 from typing import Optional
 
 from httpx import Response, URL, AsyncClient, HTTPStatusError
@@ -23,9 +24,62 @@ from httpx._types import (
 from loguru import logger
 from mcp.server.fastmcp.exceptions import ToolError
 
+from basic_memory import telemetry
 from basic_memory.config import ConfigManager
 
 
+def _classify_http_outcome(status_code: int) -> str:
+    """Map HTTP status codes to a low-cardinality outcome label."""
+    if 200 <= status_code < 300:
+        return "success"
+    if 300 <= status_code < 400:  # pragma: no cover
+        return "redirect"
+    if 400 <= status_code < 500:
+        return "client_error"
+    if 500 <= status_code < 600:
+        return "server_error"
+    return "unknown"  # pragma: no cover
+
+
+class _RequestSpan:
+    """Small adapter for attaching outcome metadata to a live request span."""
+
+    def __init__(self, active_span: typing.Any | None):
+        self._active_span = active_span
+
+    def record_response(self, response: Response) -> None:
+        self._set_attributes(
+            {
+                "status_code": response.status_code,
+                "is_success": response.is_success,
+                "outcome": _classify_http_outcome(response.status_code),
+            }
+        )
+
+    def record_transport_error(self, exc: Exception) -> None:
+        self._set_attributes(
+            {
+                "is_success": False,
+                "outcome": "transport_error",
+                "error_type": type(exc).__name__,
+            }
+        )
+
+    def _set_attributes(self, attrs: dict[str, typing.Any]) -> None:
+        if self._active_span is None:
+            return
+
+        set_attributes = getattr(self._active_span, "set_attributes", None)
+        if callable(set_attributes):
+            set_attributes(attrs)
+            return
+
+        set_attribute = getattr(self._active_span, "set_attribute", None)
+        if callable(set_attribute):
+            for key, value in attrs.items():
+                set_attribute(key, value)
+
+
 def get_error_message(
     status_code: int, url: URL | str, method: str, msg: Optional[str] = None
 ) -> str:
@@ -135,10 +189,38 @@ def _resolve_error_message(
     return get_error_message(status_code, url, method)
 
 
+@contextmanager
+def _request_scope(
+    method: str,
+    *,
+    client_name: str | None,
+    operation: str | None,
+    path_template: str | None,
+    params: QueryParamTypes | None = None,
+    has_body: bool = False,
+):
+    """Create the shared MCP transport span used by all HTTP helpers."""
+    attrs = {
+        "method": method,
+        "client_name": client_name,
+        "operation": operation,
+        "path_template": path_template,
+        "phase": "request",
+        "has_query": bool(params),
+        "has_body": has_body,
+    }
+    with telemetry.contextualize(**attrs):
+        with telemetry.started_span("mcp.http.request", **attrs) as active_span:
+            yield _RequestSpan(active_span)
+
+
 async def call_get(
     client: AsyncClient,
     url: URL | str,
     *,
+    client_name: str | None = None,
+    operation: str | None = None,
+    path_template: str | None = None,
     params: QueryParamTypes | None = None,
     headers: HeaderTypes | None = None,
     cookies: CookieTypes | None = None,
@@ -168,18 +250,27 @@ async def call_get(
     """
     logger.debug(f"Calling GET '{url}' params: '{params}'")
     error_message = None
+    request_span: _RequestSpan | None = None
 
     try:
-        response = await client.get(
-            url,
+        with _request_scope(
+            "GET",
+            client_name=client_name,
+            operation=operation,
+            path_template=path_template,
             params=params,
-            headers=headers,
-            cookies=cookies,
-            auth=auth,
-            follow_redirects=follow_redirects,
-            timeout=timeout,
-            extensions=extensions,
-        )
+        ) as request_span:
+            response = await client.get(
+                url,
+                params=params,
+                headers=headers,
+                cookies=cookies,
+                auth=auth,
+                follow_redirects=follow_redirects,
+                timeout=timeout,
+                extensions=extensions,
+            )
+            request_span.record_response(response)
 
         if response.is_success:
             return response
@@ -206,12 +297,19 @@ async def call_get(
 
     except HTTPStatusError as e:
         raise ToolError(error_message) from e
+    except Exception as e:
+        if request_span is not None:
+            request_span.record_transport_error(e)
+        raise
 
 
 async def call_put(
     client: AsyncClient,
     url: URL | str,
     *,
+    client_name: str | None = None,
+    operation: str | None = None,
+    path_template: str | None = None,
     content: RequestContent | None = None,
     data: RequestData | None = None,
     files: RequestFiles | None = None,
@@ -249,22 +347,32 @@ async def call_put(
     """
     logger.debug(f"Calling PUT '{url}'")
     error_message = None
+    request_span: _RequestSpan | None = None
 
     try:
-        response = await client.put(
-            url,
-            content=content,
-            data=data,
-            files=files,
-            json=json,
+        with _request_scope(
+            "PUT",
+            client_name=client_name,
+            operation=operation,
+            path_template=path_template,
             params=params,
-            headers=headers,
-            cookies=cookies,
-            auth=auth,
-            follow_redirects=follow_redirects,
-            timeout=timeout,
-            extensions=extensions,
-        )
+            has_body=any(value is not None for value in (content, data, files, json)),
+        ) as request_span:
+            response = await client.put(
+                url,
+                content=content,
+                data=data,
+                files=files,
+                json=json,
+                params=params,
+                headers=headers,
+                cookies=cookies,
+                auth=auth,
+                follow_redirects=follow_redirects,
+                timeout=timeout,
+                extensions=extensions,
+            )
+            request_span.record_response(response)
 
         if response.is_success:
             return response
@@ -292,12 +400,19 @@ async def call_put(
 
     except HTTPStatusError as e:
         raise ToolError(error_message) from e
+    except Exception as e:
+        if request_span is not None:
+            request_span.record_transport_error(e)
+        raise
 
 
 async def call_patch(
     client: AsyncClient,
     url: URL | str,
     *,
+    client_name: str | None = None,
+    operation: str | None = None,
+    path_template: str | None = None,
     content: RequestContent | None = None,
     data: RequestData | None = None,
     files: RequestFiles | None = None,
@@ -334,22 +449,32 @@ async def call_patch(
         ToolError: If the request fails with an appropriate error message
     """
     logger.debug(f"Calling PATCH '{url}'")
+    request_span: _RequestSpan | None = None
 
     try:
-        response = await client.patch(
-            url,
-            content=content,
-            data=data,
-            files=files,
-            json=json,
+        with _request_scope(
+            "PATCH",
+            client_name=client_name,
+            operation=operation,
+            path_template=path_template,
             params=params,
-            headers=headers,
-            cookies=cookies,
-            auth=auth,
-            follow_redirects=follow_redirects,
-            timeout=timeout,
-            extensions=extensions,
-        )
+            has_body=any(value is not None for value in (content, data, files, json)),
+        ) as request_span:
+            response = await client.patch(
+                url,
+                content=content,
+                data=data,
+                files=files,
+                json=json,
+                params=params,
+                headers=headers,
+                cookies=cookies,
+                auth=auth,
+                follow_redirects=follow_redirects,
+                timeout=timeout,
+                extensions=extensions,
+            )
+            request_span.record_response(response)
 
         if response.is_success:
             return response
@@ -382,12 +507,19 @@ async def call_patch(
         error_message = _resolve_error_message(status_code, url, "PATCH", response_data)
 
         raise ToolError(error_message) from e
+    except Exception as e:
+        if request_span is not None:
+            request_span.record_transport_error(e)
+        raise
 
 
 async def call_post(
     client: AsyncClient,
     url: URL | str,
     *,
+    client_name: str | None = None,
+    operation: str | None = None,
+    path_template: str | None = None,
     content: RequestContent | None = None,
     data: RequestData | None = None,
     files: RequestFiles | None = None,
@@ -425,23 +557,33 @@ async def call_post(
     """
     logger.debug(f"Calling POST '{url}'")
     error_message = None
+    request_span: _RequestSpan | None = None
 
     try:
-        response = await client.post(
-            url=url,
-            content=content,
-            data=data,
-            files=files,
-            json=json,
+        with _request_scope(
+            "POST",
+            client_name=client_name,
+            operation=operation,
+            path_template=path_template,
             params=params,
-            headers=headers,
-            cookies=cookies,
-            auth=auth,
-            follow_redirects=follow_redirects,
-            timeout=timeout,
-            extensions=extensions,
-        )
-        logger.debug(f"response: {response.json()}")
+            has_body=any(value is not None for value in (content, data, files, json)),
+        ) as request_span:
+            response = await client.post(
+                url=url,
+                content=content,
+                data=data,
+                files=files,
+                json=json,
+                params=params,
+                headers=headers,
+                cookies=cookies,
+                auth=auth,
+                follow_redirects=follow_redirects,
+                timeout=timeout,
+                extensions=extensions,
+            )
+            request_span.record_response(response)
+        logger.debug(f"response: {_extract_response_data(response)}")
 
         if response.is_success:
             return response
@@ -468,6 +610,10 @@ async def call_post(
 
     except HTTPStatusError as e:
         raise ToolError(error_message) from e
+    except Exception as e:
+        if request_span is not None:
+            request_span.record_transport_error(e)
+        raise
 
 
 async def resolve_entity_id(client: AsyncClient, project_external_id: str, identifier: str) -> str:
@@ -506,6 +652,9 @@ async def call_delete(
     client: AsyncClient,
     url: URL | str,
     *,
+    client_name: str | None = None,
+    operation: str | None = None,
+    path_template: str | None = None,
     params: QueryParamTypes | None = None,
     headers: HeaderTypes | None = None,
     cookies: CookieTypes | None = None,
@@ -535,18 +684,27 @@ async def call_delete(
     """
     logger.debug(f"Calling DELETE '{url}'")
     error_message = None
+    request_span: _RequestSpan | None = None
 
     try:
-        response = await client.delete(
-            url=url,
+        with _request_scope(
+            "DELETE",
+            client_name=client_name,
+            operation=operation,
+            path_template=path_template,
             params=params,
-            headers=headers,
-            cookies=cookies,
-            auth=auth,
-            follow_redirects=follow_redirects,
-            timeout=timeout,
-            extensions=extensions,
-        )
+        ) as request_span:
+            response = await client.delete(
+                url=url,
+                params=params,
+                headers=headers,
+                cookies=cookies,
+                auth=auth,
+                follow_redirects=follow_redirects,
+                timeout=timeout,
+                extensions=extensions,
+            )
+            request_span.record_response(response)
 
         if response.is_success:
             return response
@@ -573,3 +731,7 @@ async def call_delete(
 
     except HTTPStatusError as e:
         raise ToolError(error_message) from e
+    except Exception as e:
+        if request_span is not None:
+            request_span.record_transport_error(e)
+        raise

src/basic_memory/mcp/tools/write_note.py

@@ -1,16 +1,18 @@
 """Write note tool for Basic Memory MCP server."""
 
 import textwrap
-from typing import List, Union, Optional, Literal
+from typing import Annotated, List, Union, Optional, Literal
 
 from loguru import logger
+from pydantic import BeforeValidator
 
+from basic_memory import telemetry
 from basic_memory.config import ConfigManager
 from basic_memory.mcp.project_context import get_project_client, add_project_metadata
 from basic_memory.mcp.server import mcp
 from fastmcp import Context
 from basic_memory.schemas.base import Entity
-from basic_memory.utils import parse_tags, validate_project_path
+from basic_memory.utils import coerce_dict, parse_tags, validate_project_path
 
 # Define TagType as a Union that can accept either a string or a list of strings or None
 TagType = Union[List[str], str, None]
@@ -28,7 +30,7 @@ async def write_note(
     workspace: Optional[str] = None,
     tags: list[str] | str | None = None,
     note_type: str = "note",
-    metadata: dict | None = None,
+    metadata: Annotated[dict | None, BeforeValidator(coerce_dict)] = None,
     overwrite: bool | None = None,
     output_format: Literal["text", "json"] = "text",
     context: Context | None = None,
@@ -147,161 +149,180 @@ async def write_note(
         overwrite if overwrite is not None else ConfigManager().config.write_note_overwrite_default
     )
 
-    async with get_project_client(project, workspace, context) as (client, active_project):
-        logger.info(
-            f"MCP tool call tool=write_note project={active_project.name} directory={directory}, title={title}, tags={tags}"
-        )
-
-        # Normalize "/" to empty string for root directory (must happen before validation)
-        if directory == "/":
-            directory = ""
-
-        # Validate directory path to prevent path traversal attacks
-        project_path = active_project.home
-        if directory and not validate_project_path(directory, project_path):
-            logger.warning(
-                "Attempted path traversal attack blocked",
-                directory=directory,
-                project=active_project.name,
-            )
-            if output_format == "json":
-                return {
-                    "title": title,
-                    "permalink": None,
-                    "file_path": None,
-                    "checksum": None,
-                    "action": "created",
-                    "error": "SECURITY_VALIDATION_ERROR",
-                }
-            return f"# Error\n\nDirectory path '{directory}' is not allowed - paths must stay within project boundaries"
-
-        # Process tags using the helper function
-        tag_list = parse_tags(tags)
-
-        # Build entity_metadata from optional metadata, then explicit tags on top
-        # Order matters: explicit tags parameter takes precedence over metadata["tags"]
-        entity_metadata = {}
-        if metadata:
-            entity_metadata.update(metadata)
-        if tag_list:
-            entity_metadata["tags"] = tag_list
-
-        entity = Entity(
-            title=title,
-            directory=directory,
-            note_type=note_type,
-            content_type="text/markdown",
-            content=content,
-            entity_metadata=entity_metadata or None,
-        )
-
-        # Import here to avoid circular import
-        from basic_memory.mcp.clients import KnowledgeClient
-
-        # Use typed KnowledgeClient for API calls
-        knowledge_client = KnowledgeClient(client, active_project.external_id)
-
-        # Try to create the entity first (optimistic create)
-        logger.debug(f"Attempting to create entity permalink={entity.permalink}")
-        action = "Created"  # Default to created
-        try:
-            result = await knowledge_client.create_entity(entity.model_dump(), fast=False)
-            action = "Created"
-        except Exception as e:
-            # If creation failed due to conflict (already exists), try to update
-            if (
-                "409" in str(e)
-                or "conflict" in str(e).lower()
-                or "already exists" in str(e).lower()
+    with telemetry.operation(
+        "mcp.tool.write_note",
+        entrypoint="mcp",
+        tool_name="write_note",
+        requested_project=project,
+        workspace_id=workspace,
+        note_type=note_type,
+        overwrite=effective_overwrite,
+        output_format=output_format,
+    ):
+        async with get_project_client(project, workspace, context) as (client, active_project):
+            with telemetry.contextualize(
+                project_name=active_project.name,
+                workspace_id=workspace,
+                tool_name="write_note",
             ):
-                # Guard: block overwrite unless explicitly enabled
-                if not effective_overwrite:
+                logger.info(
+                    f"MCP tool call tool=write_note project={active_project.name} directory={directory}, title={title}, tags={tags}"
+                )
+
+                # Normalize "/" to empty string for root directory (must happen before validation)
+                if directory == "/":
+                    directory = ""
+
+                # Validate directory path to prevent path traversal attacks
+                project_path = active_project.home
+                if directory and not validate_project_path(directory, project_path):
                     logger.warning(
-                        f"write_note blocked: note already exists (overwrite not enabled) "
-                        f"permalink={entity.permalink}"
+                        "Attempted path traversal attack blocked",
+                        directory=directory,
+                        project=active_project.name,
                     )
                     if output_format == "json":
                         return {
                             "title": title,
-                            "permalink": entity.permalink,
+                            "permalink": None,
                             "file_path": None,
                             "checksum": None,
-                            "action": "conflict",
-                            "error": "NOTE_ALREADY_EXISTS",
+                            "action": "created",
+                            "error": "SECURITY_VALIDATION_ERROR",
                         }
-                    return _format_overwrite_error(title, entity.permalink, active_project.name)
+                    return f"# Error\n\nDirectory path '{directory}' is not allowed - paths must stay within project boundaries"
 
-                logger.debug(f"Entity exists, updating instead permalink={entity.permalink}")
+                # Process tags using the helper function
+                tag_list = parse_tags(tags)
+
+                # Build entity_metadata from optional metadata, then explicit tags on top
+                # Order matters: explicit tags parameter takes precedence over metadata["tags"]
+                entity_metadata = {}
+                if metadata:
+                    entity_metadata.update(metadata)
+                if tag_list:
+                    entity_metadata["tags"] = tag_list
+
+                entity = Entity(
+                    title=title,
+                    directory=directory,
+                    note_type=note_type,
+                    content_type="text/markdown",
+                    content=content,
+                    entity_metadata=entity_metadata or None,
+                )
+
+                # Import here to avoid circular import
+                from basic_memory.mcp.clients import KnowledgeClient
+
+                # Use typed KnowledgeClient for API calls
+                knowledge_client = KnowledgeClient(client, active_project.external_id)
+
+                # Try to create the entity first (optimistic create)
+                logger.debug(f"Attempting to create entity permalink={entity.permalink}")
+                action = "Created"  # Default to created
                 try:
-                    if not entity.permalink:
-                        raise ValueError(
-                            "Entity permalink is required for updates"
-                        )  # pragma: no cover
-                    entity_id = await knowledge_client.resolve_entity(entity.permalink)
-                    result = await knowledge_client.update_entity(
-                        entity_id, entity.model_dump(), fast=False
-                    )
-                    action = "Updated"
-                except Exception as update_error:  # pragma: no cover
-                    # Re-raise the original error if update also fails
-                    raise e from update_error  # pragma: no cover
-            else:
-                # Re-raise if it's not a conflict error
-                raise  # pragma: no cover
-        summary = [
-            f"# {action} note",
-            f"project: {active_project.name}",
-            f"file_path: {result.file_path}",
-            f"permalink: {result.permalink}",
-            f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
-        ]
+                    result = await knowledge_client.create_entity(entity.model_dump(), fast=False)
+                    action = "Created"
+                except Exception as e:
+                    # If creation failed due to conflict (already exists), try to update
+                    if (
+                        "409" in str(e)
+                        or "conflict" in str(e).lower()
+                        or "already exists" in str(e).lower()
+                    ):
+                        # Guard: block overwrite unless explicitly enabled
+                        if not effective_overwrite:
+                            logger.warning(
+                                f"write_note blocked: note already exists (overwrite not enabled) "
+                                f"permalink={entity.permalink}"
+                            )
+                            if output_format == "json":
+                                return {
+                                    "title": title,
+                                    "permalink": entity.permalink,
+                                    "file_path": None,
+                                    "checksum": None,
+                                    "action": "conflict",
+                                    "error": "NOTE_ALREADY_EXISTS",
+                                }
+                            return _format_overwrite_error(
+                                title, entity.permalink, active_project.name
+                            )
 
-        # Count observations by category
-        categories = {}
-        if result.observations:
-            for obs in result.observations:
-                categories[obs.category] = categories.get(obs.category, 0) + 1
+                        logger.debug(
+                            f"Entity exists, updating instead permalink={entity.permalink}"
+                        )
+                        try:
+                            if not entity.permalink:
+                                raise ValueError(
+                                    "Entity permalink is required for updates"
+                                )  # pragma: no cover
+                            entity_id = await knowledge_client.resolve_entity(entity.permalink)
+                            result = await knowledge_client.update_entity(
+                                entity_id, entity.model_dump(), fast=False
+                            )
+                            action = "Updated"
+                        except Exception as update_error:  # pragma: no cover
+                            # Re-raise the original error if update also fails
+                            raise e from update_error  # pragma: no cover
+                    else:
+                        # Re-raise if it's not a conflict error
+                        raise  # pragma: no cover
+                summary = [
+                    f"# {action} note",
+                    f"project: {active_project.name}",
+                    f"file_path: {result.file_path}",
+                    f"permalink: {result.permalink}",
+                    f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
+                ]
 
-            summary.append("\n## Observations")
-            for category, count in sorted(categories.items()):
-                summary.append(f"- {category}: {count}")
+                # Count observations by category
+                categories = {}
+                if result.observations:
+                    for obs in result.observations:
+                        categories[obs.category] = categories.get(obs.category, 0) + 1
 
-        # Count resolved/unresolved relations
-        unresolved = 0
-        resolved = 0
-        if result.relations:
-            unresolved = sum(1 for r in result.relations if not r.to_id)
-            resolved = len(result.relations) - unresolved
+                    summary.append("\n## Observations")
+                    for category, count in sorted(categories.items()):
+                        summary.append(f"- {category}: {count}")
 
-            summary.append("\n## Relations")
-            summary.append(f"- Resolved: {resolved}")
-            if unresolved:
-                summary.append(f"- Unresolved: {unresolved}")
-                summary.append(
-                    "\nNote: Unresolved relations point to entities that don't exist yet."
-                )
-                summary.append(
-                    "They will be automatically resolved when target entities are created or during sync operations."
+                # Count resolved/unresolved relations
+                unresolved = 0
+                resolved = 0
+                if result.relations:
+                    unresolved = sum(1 for r in result.relations if not r.to_id)
+                    resolved = len(result.relations) - unresolved
+
+                    summary.append("\n## Relations")
+                    summary.append(f"- Resolved: {resolved}")
+                    if unresolved:
+                        summary.append(f"- Unresolved: {unresolved}")
+                        summary.append(
+                            "\nNote: Unresolved relations point to entities that don't exist yet."
+                        )
+                        summary.append(
+                            "They will be automatically resolved when target entities are created or during sync operations."
+                        )
+
+                if tag_list:
+                    summary.append(f"\n## Tags\n- {', '.join(tag_list)}")
+
+                # Log the response with structured data
+                logger.info(
+                    f"MCP tool response: tool=write_note project={active_project.name} action={action} permalink={result.permalink} observations_count={len(result.observations)} relations_count={len(result.relations)} resolved_relations={resolved} unresolved_relations={unresolved}"
                 )
+                if output_format == "json":
+                    return {
+                        "title": result.title,
+                        "permalink": result.permalink,
+                        "file_path": result.file_path,
+                        "checksum": result.checksum,
+                        "action": action.lower(),
+                    }
 
-        if tag_list:
-            summary.append(f"\n## Tags\n- {', '.join(tag_list)}")
-
-        # Log the response with structured data
-        logger.info(
-            f"MCP tool response: tool=write_note project={active_project.name} action={action} permalink={result.permalink} observations_count={len(result.observations)} relations_count={len(result.relations)} resolved_relations={resolved} unresolved_relations={unresolved}"
-        )
-        if output_format == "json":
-            return {
-                "title": result.title,
-                "permalink": result.permalink,
-                "file_path": result.file_path,
-                "checksum": result.checksum,
-                "action": action.lower(),
-            }
-
-        summary_result = "\n".join(summary)
-        return add_project_metadata(summary_result, active_project.name)
+                summary_result = "\n".join(summary)
+                return add_project_metadata(summary_result, active_project.name)
 
 
 def _format_overwrite_error(title: str, permalink: str | None, project_name: str) -> str:

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,21 +64,21 @@ 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)
+        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) -> Optional[Entity]:
+    async def get_by_permalink(
+        self, permalink: str, *, load_relations: bool = True
+    ) -> Optional[Entity]:
         """Get entity by permalink.
 
         Args:
             permalink: Unique identifier for the entity
         """
-        query = self.select().where(Entity.permalink == permalink).options(*self.get_load_options())
-        return await self.find_one(query)
+        query = self.select().where(Entity.permalink == permalink)
+        return await self._find_one_by_query(query, load_relations=load_relations)
 
-    async def get_by_title(self, title: str) -> Sequence[Entity]:
+    async def get_by_title(self, title: str, *, load_relations: bool = True) -> Sequence[Entity]:
         """Get entities by title, ordered by shortest path first.
 
         When multiple entities share the same title (in different folders),
@@ -82,23 +92,20 @@ class EntityRepository(Repository[Entity]):
             self.select()
             .where(Entity.title == title)
             .order_by(func.length(Entity.file_path), Entity.file_path)
-            .options(*self.get_load_options())
         )
-        result = await self.execute_query(query)
+        result = await self.execute_query(query, use_query_options=load_relations)
         return list(result.scalars().all())
 
-    async def get_by_file_path(self, file_path: Union[Path, str]) -> Optional[Entity]:
+    async def get_by_file_path(
+        self, file_path: Union[Path, str], *, load_relations: bool = True
+    ) -> Optional[Entity]:
         """Get entity by file_path.
 
         Args:
             file_path: Path to the entity file (will be converted to string internally)
         """
-        query = (
-            self.select()
-            .where(Entity.file_path == Path(file_path).as_posix())
-            .options(*self.get_load_options())
-        )
-        return await self.find_one(query)
+        query = self.select().where(Entity.file_path == Path(file_path).as_posix())
+        return await self._find_one_by_query(query, load_relations=load_relations)
 
     # -------------------------------------------------------------------------
     # Lightweight methods for permalink resolution (no eager loading)
@@ -381,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:

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,7 +268,7 @@ 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) -> Optional[T]:
+    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:
@@ -279,12 +279,13 @@ class Repository[T: Base]:
                 entity = result.scalars().one()
 
                 if isinstance(entity_data, dict):
-                    for key, value in entity_data.items():
-                        if key in self.valid_columns:
-                            setattr(entity, key, value)
+                    update_data = cast(dict[str, Any], entity_data)
+                    for key in self.valid_columns:
+                        if key in update_data:
+                            setattr(entity, key, update_data[key])
 
                 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

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

@@ -7,6 +7,7 @@ Composition roots (containers) read ConfigManager and use this module
 to resolve the runtime mode, then pass the result downstream.
 """
 
+import os
 from enum import Enum, auto
 
 
@@ -44,10 +45,16 @@ def resolve_runtime_mode(
     Returns:
         The resolved RuntimeMode
     """
-    # Trigger: test environment is detected
-    # Why: tests need special handling (no file sync, isolated DB)
-    # Outcome: returns TEST mode, skipping cloud mode check
     if is_test_env:
         return RuntimeMode.TEST
 
+    # Trigger: BASIC_MEMORY_CLOUD_MODE env var is set
+    # Why: cloud deployments must not start local file sync — cloud handles
+    #      file storage via S3/Tigris, and the local sync tries to open a
+    #      SQLite/Postgres DB that doesn't exist in the cloud container
+    # Outcome: returns CLOUD mode, skipping file sync initialization
+    cloud_mode = os.getenv("BASIC_MEMORY_CLOUD_MODE", "").lower() in ("1", "true")
+    if cloud_mode:
+        return RuntimeMode.CLOUD
+
     return RuntimeMode.LOCAL

src/basic_memory/schemas/base.py

@@ -140,10 +140,12 @@ def validate_timeframe(timeframe: str) -> str:
     if parsed > now:
         raise ValueError("Timeframe cannot be in the future")  # pragma: no cover
 
-    # Could format the duration back to our standard format
-    days = (now - parsed).days
+    # Round to nearest day to handle DST transitions where an hour shift
+    # can cause e.g. "7d" to compute as 6 days + 23 hours
+    total_seconds = (now - parsed).total_seconds()
+    days = round(total_seconds / 86400)
 
-    # Could enforce reasonable limits
+    # Enforce reasonable limits
     if days > 365:
         raise ValueError("Timeframe should be <= 1 year")
 
@@ -176,8 +178,13 @@ ContentType = Annotated[
 ]
 
 
-RelationType = Annotated[str, MinLen(1), MaxLen(200)]
-"""Type of relationship between entities. Always use active voice present tense."""
+RelationType = Annotated[str, MinLen(1)]
+"""Type of relationship between entities. Always use active voice present tense.
+
+The database stores relation_type as an unrestricted string, and response models
+need to tolerate existing long-form values written by LLMs. Keeping an API-only
+200-character cap here causes reads to fail for valid stored data.
+"""
 
 ObservationStr = Annotated[
     str,

src/basic_memory/schemas/cloud.py

@@ -1,7 +1,11 @@
 """Schemas for cloud-related API responses."""
 
+from typing import Literal
+
 from pydantic import BaseModel, Field
 
+type ProjectVisibility = Literal["workspace", "shared", "private"]
+
 
 class TenantMountInfo(BaseModel):
     """Response from /tenant/mount/info endpoint."""
@@ -36,6 +40,10 @@ class CloudProjectCreateRequest(BaseModel):
     name: str = Field(..., description="Project name")
     path: str = Field(..., description="Project path (permalink)")
     set_default: bool = Field(default=False, description="Set as default project")
+    visibility: ProjectVisibility = Field(
+        default="workspace",
+        description="Project visibility for team workspaces",
+    )
 
 
 class CloudProjectCreateResponse(BaseModel):
@@ -73,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/request.py

@@ -65,7 +65,14 @@ class EditEntityRequest(BaseModel):
     Supports various operation types for different editing scenarios.
     """
 
-    operation: Literal["append", "prepend", "find_replace", "replace_section"]
+    operation: Literal[
+        "append",
+        "prepend",
+        "find_replace",
+        "replace_section",
+        "insert_before_section",
+        "insert_after_section",
+    ]
     content: str
     section: Optional[str] = None
     find_text: Optional[str] = None
@@ -75,8 +82,16 @@ class EditEntityRequest(BaseModel):
     @classmethod
     def validate_section_for_replace_section(cls, v, info):
         """Ensure section is provided for replace_section operation."""
-        if info.data.get("operation") == "replace_section" and not v:
-            raise ValueError("section parameter is required for replace_section operation")
+        if (
+            info.data.get("operation")
+            in (
+                "replace_section",
+                "insert_before_section",
+                "insert_after_section",
+            )
+            and not v
+        ):
+            raise ValueError("section parameter is required for section-based operations")
         return v
 
     @field_validator("find_text")

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/schemas/v2/__init__.py

@@ -10,6 +10,11 @@ from basic_memory.schemas.v2.entity import (
     ProjectResolveRequest,
     ProjectResolveResponse,
 )
+from basic_memory.schemas.v2.graph import (
+    GraphEdge,
+    GraphNode,
+    GraphResponse,
+)
 from basic_memory.schemas.v2.resource import (
     CreateResourceRequest,
     UpdateResourceRequest,
@@ -25,6 +30,9 @@ __all__ = [
     "DeleteDirectoryRequestV2",
     "ProjectResolveRequest",
     "ProjectResolveResponse",
+    "GraphEdge",
+    "GraphNode",
+    "GraphResponse",
     "CreateResourceRequest",
     "UpdateResourceRequest",
     "ResourceResponse",

src/basic_memory/schemas/v2/graph.py

@@ -0,0 +1,31 @@
+"""Graph visualization schemas for the knowledge graph endpoint."""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class GraphNode(BaseModel):
+    """A node in the knowledge graph visualization."""
+
+    external_id: str = Field(..., description="Entity external ID (UUID)")
+    title: str = Field(..., description="Entity title")
+    note_type: Optional[str] = Field(None, description="Note type (e.g., note, spec, task)")
+    file_path: str = Field(..., description="Relative file path")
+
+
+class GraphEdge(BaseModel):
+    """An edge in the knowledge graph visualization."""
+
+    from_id: str = Field(..., description="External ID of source entity")
+    to_id: str = Field(..., description="External ID of target entity")
+    relation_type: str = Field(..., description="Type of relation")
+
+
+class GraphResponse(BaseModel):
+    """Complete knowledge graph for visualization."""
+
+    nodes: list[GraphNode] = Field(default_factory=list, description="All entities as nodes")
+    edges: list[GraphEdge] = Field(
+        default_factory=list, description="All resolved relations as edges"
+    )

src/basic_memory/services/context_service.py

@@ -10,6 +10,7 @@ from typing import List, Optional, Tuple, TYPE_CHECKING
 from loguru import logger
 from sqlalchemy import text
 
+from basic_memory import telemetry
 from basic_memory.repository.entity_repository import EntityRepository
 from basic_memory.repository.observation_repository import ObservationRepository
 from basic_memory.repository.postgres_search_repository import PostgresSearchRepository
@@ -110,146 +111,162 @@ class ContextService:
             f"Building context for URI: '{memory_url}' depth: '{depth}' since: '{since}' limit: '{limit}' offset: '{offset}'  max_related: '{max_related}'"
         )
 
-        # Fetch one extra item to detect whether more pages exist (N+1 trick)
-        fetch_limit = limit + 1
+        with telemetry.scope(
+            "memory.build_context",
+            domain="memory",
+            action="build_context",
+            phase="build_context",
+            limit=limit,
+            offset=offset,
+        ):
+            fetch_limit = limit + 1
 
-        normalized_path: Optional[str] = None
-        if memory_url:
-            path = memory_url_path(memory_url)
-            # Check for wildcards before normalization
-            has_wildcard = "*" in path
+            normalized_path: Optional[str] = None
+            with telemetry.scope(
+                "memory.build_context.resolve_primary",
+                domain="memory",
+                action="build_context",
+                phase="resolve_primary",
+            ):
+                if memory_url:
+                    path = memory_url_path(memory_url)
+                    has_wildcard = "*" in path
 
-            if has_wildcard:
-                # For wildcard patterns, normalize each segment separately to preserve the *
-                parts = path.split("*")
-                normalized_parts = [
-                    generate_permalink(part, split_extension=False) if part else ""
-                    for part in parts
-                ]
-                normalized_path = "*".join(normalized_parts)
-                logger.debug(f"Pattern search for '{normalized_path}'")
-                primary = await self.search_repository.search(
-                    permalink_match=normalized_path, limit=fetch_limit, offset=offset
-                )
-            else:
-                # For exact paths, normalize the whole thing
-                normalized_path = generate_permalink(path, split_extension=False)
-                logger.debug(f"Direct lookup for '{normalized_path}'")
-                primary = await self.search_repository.search(
-                    permalink=normalized_path, limit=fetch_limit, offset=offset
-                )
-
-                # Trigger: exact permalink lookup returned no results
-                # Why: the identifier may be valid but not an exact permalink match
-                #      (e.g., missing project prefix, title instead of permalink)
-                # Outcome: use LinkResolver's multi-strategy resolution to find the entity,
-                #          then retry search with its actual permalink
-                if not primary and self.link_resolver:
-                    entity = await self.link_resolver.resolve_link(
-                        path, use_search=True, strict=False
-                    )
-                    if entity:
-                        logger.debug(
-                            f"LinkResolver resolved '{path}' to permalink '{entity.permalink}'"
-                        )
-                        normalized_path = entity.permalink
+                    if has_wildcard:
+                        parts = path.split("*")
+                        normalized_parts = [
+                            generate_permalink(part, split_extension=False) if part else ""
+                            for part in parts
+                        ]
+                        normalized_path = "*".join(normalized_parts)
+                        logger.debug(f"Pattern search for '{normalized_path}'")
                         primary = await self.search_repository.search(
-                            permalink=entity.permalink, limit=fetch_limit, offset=offset
+                            permalink_match=normalized_path, limit=fetch_limit, offset=offset
                         )
-        else:
-            logger.debug(f"Build context for '{types}'")
-            primary = await self.search_repository.search(
-                search_item_types=types, after_date=since, limit=fetch_limit, offset=offset
+                    else:
+                        normalized_path = generate_permalink(path, split_extension=False)
+                        logger.debug(f"Direct lookup for '{normalized_path}'")
+                        primary = await self.search_repository.search(
+                            permalink=normalized_path, limit=fetch_limit, offset=offset
+                        )
+
+                        if not primary and self.link_resolver:
+                            entity = await self.link_resolver.resolve_link(
+                                path, use_search=True, strict=False
+                            )
+                            if entity:
+                                logger.debug(
+                                    f"LinkResolver resolved '{path}' to permalink '{entity.permalink}'"
+                                )
+                                normalized_path = entity.permalink
+                                primary = await self.search_repository.search(
+                                    permalink=entity.permalink,
+                                    limit=fetch_limit,
+                                    offset=offset,
+                                )
+                else:
+                    logger.debug(f"Build context for '{types}'")
+                    primary = await self.search_repository.search(
+                        search_item_types=types,
+                        after_date=since,
+                        limit=fetch_limit,
+                        offset=offset,
+                    )
+
+            has_more = len(primary) > limit
+            if has_more:
+                primary = primary[:limit]
+
+            type_id_pairs = [(r.type, r.id) for r in primary] if primary else []
+            logger.debug(f"found primary type_id_pairs: {len(type_id_pairs)}")
+
+            with telemetry.scope(
+                "memory.build_context.find_related",
+                domain="memory",
+                action="build_context",
+                phase="find_related",
+            ):
+                related = await self.find_related(
+                    type_id_pairs, max_depth=depth, since=since, max_results=max_related
+                )
+            logger.debug(f"Found {len(related)} related results")
+
+            entity_ids = []
+            for result in primary:
+                if result.type == SearchItemType.ENTITY.value:
+                    entity_ids.append(result.id)
+
+            for result in related:
+                if result.type == SearchItemType.ENTITY.value:
+                    entity_ids.append(result.id)
+
+            observations_by_entity = {}
+            if include_observations and entity_ids:
+                with telemetry.scope(
+                    "memory.build_context.load_observations",
+                    domain="memory",
+                    action="build_context",
+                    phase="load_observations",
+                    result_count=len(entity_ids),
+                ):
+                    observations_by_entity = await self.observation_repository.find_by_entities(
+                        entity_ids
+                    )
+                logger.debug(f"Found observations for {len(observations_by_entity)} entities")
+
+            metadata = ContextMetadata(
+                uri=normalized_path if memory_url else None,
+                types=types,
+                depth=depth,
+                timeframe=since.isoformat() if since else None,
+                primary_count=len(primary),
+                related_count=len(related),
+                total_observations=sum(len(obs) for obs in observations_by_entity.values()),
+                total_relations=sum(1 for r in related if r.type == SearchItemType.RELATION),
+                has_more=has_more,
             )
 
-        # Trim to requested limit and set has_more flag
-        has_more = len(primary) > limit
-        if has_more:
-            primary = primary[:limit]
+            with telemetry.scope(
+                "memory.build_context.shape_results",
+                domain="memory",
+                action="build_context",
+                phase="shape_results",
+                result_count=len(primary),
+            ):
+                context_results = []
+                for primary_item in primary:
+                    related_to_primary = [r for r in related if r.root_id == primary_item.id]
 
-        # Get type_id pairs for traversal
+                    item_observations = []
+                    if primary_item.type == SearchItemType.ENTITY.value and include_observations:
+                        for obs in observations_by_entity.get(primary_item.id, []):
+                            item_observations.append(
+                                ContextResultRow(
+                                    type="observation",
+                                    id=obs.id,
+                                    title=f"{obs.category}: {obs.content[:50]}...",
+                                    permalink=generate_permalink(
+                                        f"{primary_item.permalink}/observations/{obs.category}/{obs.content}"
+                                    ),
+                                    file_path=primary_item.file_path,
+                                    content=obs.content,
+                                    category=obs.category,
+                                    entity_id=primary_item.id,
+                                    depth=0,
+                                    root_id=primary_item.id,
+                                    created_at=primary_item.created_at,
+                                )
+                            )
 
-        type_id_pairs = [(r.type, r.id) for r in primary] if primary else []
-        logger.debug(f"found primary type_id_pairs: {len(type_id_pairs)}")
-
-        # Find related content
-        related = await self.find_related(
-            type_id_pairs, max_depth=depth, since=since, max_results=max_related
-        )
-        logger.debug(f"Found {len(related)} related results")
-
-        # Collect entity IDs from primary and related results
-        entity_ids = []
-        for result in primary:
-            if result.type == SearchItemType.ENTITY.value:
-                entity_ids.append(result.id)
-
-        for result in related:
-            if result.type == SearchItemType.ENTITY.value:
-                entity_ids.append(result.id)
-
-        # Fetch observations for all entities if requested
-        observations_by_entity = {}
-        if include_observations and entity_ids:
-            # Use our observation repository to get observations for all entities at once
-            observations_by_entity = await self.observation_repository.find_by_entities(entity_ids)
-            logger.debug(f"Found observations for {len(observations_by_entity)} entities")
-
-        # Create metadata dataclass
-        metadata = ContextMetadata(
-            uri=normalized_path if memory_url else None,
-            types=types,
-            depth=depth,
-            timeframe=since.isoformat() if since else None,
-            primary_count=len(primary),
-            related_count=len(related),
-            total_observations=sum(len(obs) for obs in observations_by_entity.values()),
-            total_relations=sum(1 for r in related if r.type == SearchItemType.RELATION),
-            has_more=has_more,
-        )
-
-        # Build context results list directly with ContextResultItem objects
-        context_results = []
-
-        # For each primary result
-        for primary_item in primary:
-            # Find all related items with this primary item as root
-            related_to_primary = [r for r in related if r.root_id == primary_item.id]
-
-            # Get observations for this item if it's an entity
-            item_observations = []
-            if primary_item.type == SearchItemType.ENTITY.value and include_observations:
-                # Convert Observation models to ContextResultRows
-                for obs in observations_by_entity.get(primary_item.id, []):
-                    item_observations.append(
-                        ContextResultRow(
-                            type="observation",
-                            id=obs.id,
-                            title=f"{obs.category}: {obs.content[:50]}...",
-                            permalink=generate_permalink(
-                                f"{primary_item.permalink}/observations/{obs.category}/{obs.content}"
-                            ),
-                            file_path=primary_item.file_path,
-                            content=obs.content,
-                            category=obs.category,
-                            entity_id=primary_item.id,
-                            depth=0,
-                            root_id=primary_item.id,
-                            created_at=primary_item.created_at,  # created_at time from entity
+                    context_results.append(
+                        ContextResultItem(
+                            primary_result=primary_item,
+                            observations=item_observations,
+                            related_results=related_to_primary,
                         )
                     )
 
-            # Create ContextResultItem directly
-            context_item = ContextResultItem(
-                primary_result=primary_item,
-                observations=item_observations,
-                related_results=related_to_primary,
-            )
-
-            context_results.append(context_item)
-
-        # Return the structured ContextResult
-        return ContextResult(results=context_results, metadata=metadata)
+            return ContextResult(results=context_results, metadata=metadata)
 
     async def find_related(
         self,