chore: update version to 0.20.3 for v0.20.3 release

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

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.

docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-IMPLEMENTATION-PLAN.md

@@ -1,594 +0,0 @@
-# SPEC-LOCAL-GRAPH-INTELLIGENCE-IMPLEMENTATION-PLAN
-
-**Status:** Draft (Decision-Complete)  
-**Date:** 2026-03-05  
-**Owner:** Basic Memory Engineering  
-**Implementation Status (2026-03-05):** Phase 1 contract skeleton implemented in `basic-memory` branch `codex/graph-intelligence-phase1`.  
-**Related Specs:**
-1. `/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-MASTER.md`
-2. `/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-TECHNICAL-ADDENDUM.md`
-3. `/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE.md`
-
-## Scope and Intent
-
-This document is the execution handoff for Local+ Graph Intelligence.
-
-It defines exactly how we will deliver graph and FCM capabilities inside the existing Basic Memory architecture:
-1. FastAPI-first business logic.
-2. MCP and CLI as thin facades.
-3. Local/cloud contract parity.
-4. Tight build-test-iterate loop for fast delivery.
-
-This file is intentionally implementation-oriented and does not duplicate pricing narrative from the master spec.
-
-## Architecture Alignment (FastAPI-first, MCP/CLI facade)
-
-Locked architecture alignment for implementation:
-1. MCP tools remain thin proxy facades.
-2. CLI `bm tool` commands call MCP tools in JSON mode.
-3. Core logic lives in FastAPI routers and services.
-4. Cloud and local share the same REST contracts.
-5. Per-project routing continues through existing project client patterns.
-
-Execution mapping:
-1. API routers define public contracts in `/graph` and `/fcm` domains.
-2. Services own traversal, scoring, simulation, and fallback logic.
-3. Repositories and index providers own data access and graph index operations.
-4. MCP typed clients call REST endpoints and return JSON-first tool output.
-5. CLI passthrough executes tool calls and prints machine-friendly JSON.
-
-## Locked Decisions
-
-1. SQLite remains operational source for entities, relations, embeddings, and project state.
-2. Markdown remains source of truth.
-3. Oxigraph/pyoxigraph is the derived graph index for deep traversal.
-4. FCM simulation runs in Python service layer; it is not delegated to graph DB query engines.
-5. Graph index is rebuildable and disposable; stale index never blocks user workflows.
-6. FCM model and scenario artifacts persist in app database.
-7. Local+ features are gated by config flags first; entitlement wiring follows later.
-8. Graph-first vertical slices ship before deep FCM expansion.
-9. Atomic tools ship first; orchestration workflows are deferred.
-10. Existing `build_context` and `search_notes` remain backward compatible with no breaking change.
-
-## Progress Snapshot (as of 2026-03-05)
-
-Completed in Phase 1:
-1. Added `/graph` and `/fcm` v2 routers with all required contract endpoints.
-2. Added graph/FCM request and response schemas for all public API contracts.
-3. Added service-layer implementations for graph and FCM contract endpoints.
-4. Added typed MCP clients for graph and FCM API calls.
-5. Added MCP tools: `graph_lineage`, `graph_impact`, `graph_health`, `graph_reindex`, `fcm_simulate`, `fcm_rank_actions`, `fcm_import_model`, `fcm_export_model`.
-6. Added CLI passthrough commands under `bm tool ...` for all planned graph/FCM operations.
-7. Added scheduler task names for graph lifecycle: `sync_graph_entity`, `sync_graph_project`, `reindex_graph_project`.
-8. Added focused tests for API, MCP clients/tools, and CLI graph/FCM passthrough.
-9. Added fast-loop `just` targets: `test-graph-intel-api`, `test-graph-intel-mcp`, `test-graph-intel-cli`, `test-graph-intel`.
-
-Validation completed:
-1. `just test-graph-intel` passes.
-2. `ruff check` passes on changed files.
-3. `pyright` passes on changed files.
-
-Still pending after Phase 1:
-1. SQL-backed traversal/scoring for graph `lineage`, `impact`, and `health`.
-2. Oxigraph provider integration and stale-index catch-up flow.
-3. Persistent FCM model/scenario state and interop round-trip guarantees.
-4. Config-flag and entitlement gating at API/tool boundaries.
-5. Performance instrumentation and p95 envelope enforcement.
-
-## Delivery Phases
-
-### Phase 1: Contract skeleton
-
-Status: Completed (2026-03-05)
-
-Deliverables:
-1. Add `/graph` and `/fcm` API routers with request/response schemas.
-2. Add typed MCP clients for graph and FCM endpoints.
-3. Add MCP tool passthrough commands for all new operations.
-4. Add CLI `bm tool` passthrough commands mirroring MCP surface.
-5. Add minimal smoke tests for route reachability and schema validation.
-
-Exit criteria:
-1. All endpoints return structured success and error envelopes.
-2. MCP/CLI paths execute end-to-end with stubbed service responses.
-
-### Phase 2: Graph capabilities on SQL-backed logic
-
-Status: Next active phase
-
-Deliverables:
-1. Implement `lineage`, `impact`, and `health` in service layer using SQL-backed traversal and scoring.
-2. Add provenance/evidence linking in graph outputs.
-3. Add deterministic graph-health calculations for fixed snapshots.
-
-Exit criteria:
-1. `graph_lineage`, `graph_impact`, and `graph_health` pass contract tests.
-2. SQL fallback behavior is explicit and covered by tests.
-
-### Phase 3: Oxigraph derived index provider
-
-Status: Planned
-
-Deliverables:
-1. Introduce Oxigraph provider behind graph-query interface.
-2. Add lazy catch-up jobs and project-wide reindex operation.
-3. Preserve SQL fallback when index is missing or stale.
-
-Exit criteria:
-1. Stale index path serves results via SQL and schedules catch-up.
-2. Index rebuild can be triggered and completed without data loss.
-
-### Phase 4: FCM import/simulate/rank/export
-
-Status: Planned (contract endpoints complete, full behavior pending)
-
-Deliverables:
-1. Implement CSV-first import/export contracts.
-2. Implement deterministic simulation core with convergence metadata.
-3. Implement action ranking with evidence references and confidence output.
-4. Persist scenario inputs and result artifacts.
-
-Exit criteria:
-1. Research flow scenario passes: import -> simulate -> rank -> export.
-2. Interop round-trip preserves node/edge counts and signed weights.
-
-### Phase 5: Hardening
-
-Status: Planned
-
-Deliverables:
-1. Performance tuning against published latency envelopes.
-2. Local/cloud parity tests for semantics and error behavior.
-3. MCP prompt/docs updates for new graph and FCM tools.
-4. Operational docs for reindex, fallback, and troubleshooting.
-
-Exit criteria:
-1. `just check` passes before merge.
-2. Acceptance criteria in this document are fully met.
-
-## API and Interface Additions
-
-### Shared API conventions
-
-1. All endpoints are project-scoped under `/v2/projects/{project_id}`.
-2. Request and response bodies are JSON-first and agent-friendly.
-3. Success envelope is endpoint-specific payload with deterministic fields and optional probabilistic fields.
-4. Error envelope:
-```json
-{
-  "error": {
-    "code": "INVALID_ARGUMENT|NOT_FOUND|INDEX_NOT_READY|MODEL_INVALID|RESOURCE_LIMIT_EXCEEDED|INTERNAL_ERROR",
-    "message": "string",
-    "details": {}
-  }
-}
-```
-5. Latency and scale targets are p95 targets for local default hardware profile.
-
-### 1) `POST /v2/projects/{project_id}/graph/lineage`
-
-Purpose: explain decision lineage and supporting evidence paths.
-
-Request schema:
-```json
-{
-  "start": "string",
-  "goal": "string|null",
-  "max_hops": 4,
-  "relation_filters": ["string"]
-}
-```
-
-Response schema:
-```json
-{
-  "root": {"id": "string", "title": "string", "permalink": "string"},
-  "paths": [
-    {
-      "path_id": "string",
-      "nodes": [{"id": "string", "title": "string"}],
-      "edges": [{"relation": "string", "direction": "outgoing|incoming"}],
-      "deterministic_path_score": 0.0,
-      "confidence": 0.0,
-      "evidence_refs": ["memory://..."]
-    }
-  ],
-  "generated_at": "RFC3339"
-}
-```
-
-Deterministic fields: `root`, `paths.nodes`, `paths.edges`, `deterministic_path_score`, `generated_at`.  
-Probabilistic fields: `confidence`.  
-Latency target: p95 <= 450ms with `max_hops<=4`.  
-Scale envelope: up to 50k nodes and 300k edges.
-
-### 2) `POST /v2/projects/{project_id}/graph/impact`
-
-Purpose: preview impact radius before edits or decisions.
-
-Request schema:
-```json
-{
-  "target": "string",
-  "horizon": 2,
-  "relation_filters": ["string"],
-  "include_reasons": true
-}
-```
-
-Response schema:
-```json
-{
-  "target": {"id": "string", "title": "string"},
-  "affected": [
-    {
-      "id": "string",
-      "title": "string",
-      "distance": 1,
-      "impact_score": 0.0,
-      "confidence": 0.0,
-      "reasons": ["string"],
-      "evidence_refs": ["memory://..."]
-    }
-  ],
-  "summary": {"total_considered": 0, "total_returned": 0}
-}
-```
-
-Deterministic fields: membership, distance, summary counts.  
-Probabilistic fields: `impact_score`, `confidence`.  
-Latency target: p95 <= 650ms for `horizon<=3`.  
-Scale envelope: default 200 results, hard cap 1000 with pagination token.
-
-### 3) `GET /v2/projects/{project_id}/graph/health`
-
-Purpose: report deterministic graph quality and actionable issues.
-
-Query params:
-1. `scope` optional directory prefix.
-2. `timeframe` optional window like `30d`.
-
-Response schema:
-```json
-{
-  "metrics": {
-    "orphan_rate": 0.0,
-    "stale_central_nodes": 0,
-    "overloaded_hubs": 0,
-    "contradiction_candidates": 0
-  },
-  "issues": [
-    {
-      "issue_type": "orphan|stale_central|overloaded_hub|contradiction_candidate",
-      "entity_id": "string",
-      "severity": "low|medium|high",
-      "reason": "string",
-      "suggested_action": "string",
-      "confidence": 0.0
-    }
-  ],
-  "computed_at": "RFC3339"
-}
-```
-
-Deterministic fields: `metrics`, issue membership for fixed snapshot.  
-Probabilistic fields: contradiction confidence when applicable.  
-Latency target: p95 <= 1500ms project-wide, <= 700ms scoped.
-
-### 4) `POST /v2/projects/{project_id}/graph/reindex`
-
-Purpose: force project-wide graph index rebuild.
-
-Request schema:
-```json
-{
-  "mode": "full|incremental",
-  "reason": "string|null"
-}
-```
-
-Response schema:
-```json
-{
-  "job_id": "string",
-  "status": "queued|running|completed|failed",
-  "scheduled_at": "RFC3339"
-}
-```
-
-Deterministic fields: job metadata and status transitions.  
-Probabilistic fields: none.  
-Latency target: enqueue response p95 <= 120ms.
-
-### 5) `POST /v2/projects/{project_id}/fcm/simulate`
-
-Purpose: run FCM scenario simulation.
-
-Request schema:
-```json
-{
-  "actions": [{"node_id": "string", "delta": 0.2}],
-  "scenario": {
-    "steps": 12,
-    "activation": "tanh|sigmoid|bounded_linear",
-    "decay": 0.05
-  },
-  "clamp_rules": [{"node_id": "string", "min": -1.0, "max": 1.0}]
-}
-```
-
-Response schema:
-```json
-{
-  "baseline": [{"node_id": "string", "state": 0.0}],
-  "projected": [{"node_id": "string", "state": 0.0}],
-  "deltas": [{"node_id": "string", "delta": 0.0}],
-  "stability": {"converged": true, "iterations_used": 0, "residual": 0.0},
-  "confidence": 0.0,
-  "explanations": [{"node_id": "string", "top_influencers": [{"source": "string", "weight": 0.0}]}],
-  "evidence_refs": ["memory://..."]
-}
-```
-
-Deterministic fields: baseline, projected, deltas, stability for fixed model and params.  
-Probabilistic fields: confidence.  
-Latency target: p95 <= 1000ms for <=500 nodes and <=5000 edges.
-
-### 6) `POST /v2/projects/{project_id}/fcm/rank-actions`
-
-Purpose: rank candidate interventions by expected outcome and risk.
-
-Request schema:
-```json
-{
-  "goal": "string",
-  "constraints": {
-    "max_negative_impact": 0.25,
-    "required_tags": ["string"],
-    "disallowed_nodes": ["string"]
-  },
-  "top_k": 10
-}
-```
-
-Response schema:
-```json
-{
-  "goal": {"node_id": "string", "label": "string"},
-  "recommendations": [
-    {
-      "action_node_id": "string",
-      "expected_goal_delta": 0.0,
-      "risk_penalty": 0.0,
-      "net_score": 0.0,
-      "confidence": 0.0,
-      "rationale": ["string"],
-      "evidence_refs": ["memory://..."]
-    }
-  ]
-}
-```
-
-Deterministic fields: candidate set and constraint compliance.  
-Probabilistic fields: expected delta, penalty, net score, confidence.  
-Latency target: p95 <= 1500ms for top-10 from <=100 candidates.
-
-### 7) `POST /v2/projects/{project_id}/fcm/import`
-
-Purpose: import FCM model from CSV-first contract.
-
-Request schema:
-```json
-{
-  "source": "string",
-  "format": "csv_bundle_v1",
-  "merge_mode": "replace|upsert"
-}
-```
-
-Response schema:
-```json
-{
-  "import_id": "string",
-  "nodes_loaded": 0,
-  "edges_loaded": 0,
-  "warnings": ["string"],
-  "errors": ["string"]
-}
-```
-
-Deterministic fields: counts and validation diagnostics.  
-Probabilistic fields: none.  
-Latency target: p95 <= 2500ms for 10k edges import.
-
-### 8) `POST /v2/projects/{project_id}/fcm/export`
-
-Purpose: export FCM model for interoperability.
-
-Request schema:
-```json
-{
-  "format": "csv_bundle_v1",
-  "selection": {
-    "scope": "all|tag|subgraph",
-    "tag": "string|null",
-    "seed_nodes": ["string"]
-  }
-}
-```
-
-Response schema:
-```json
-{
-  "export_id": "string",
-  "format": "csv_bundle_v1",
-  "files": [{"name": "nodes.csv", "path": "string"}, {"name": "edges.csv", "path": "string"}],
-  "node_count": 0,
-  "edge_count": 0
-}
-```
-
-Deterministic fields: file names and counts for fixed selection.  
-Probabilistic fields: none.  
-Latency target: p95 <= 1800ms for 50k edges export.
-
-## Data Model and Storage Boundaries
-
-1. SQLite is mandatory operational source for entities, relations, embeddings, and project metadata.
-2. Oxigraph stores derived knowledge graph index only.
-3. FCM state persists in app database with scenario artifacts and run history.
-4. Graph index is rebuildable and disposable by design.
-5. Markdown files remain canonical source of truth.
-
-Implementation data boundaries:
-1. Knowledge graph schema tracks descriptive nodes and typed edges plus provenance.
-2. FCM schema tracks signed weighted causal edges and node states.
-3. Provenance model requires `evidence_refs`, `confidence`, and `updated_at`.
-4. Scenario model stores interventions, constraints, run parameters, and output deltas.
-5. Interop schema starts with CSV-first Mental Modeler contract.
-
-## Background Jobs and Index Lifecycle
-
-Scheduler tasks to add:
-1. `sync_graph_entity`
-2. `sync_graph_project`
-3. `reindex_graph_project`
-
-Lifecycle rules:
-1. Note writes, edits, moves, and deletes schedule graph-index sync tasks.
-2. Scheduling pattern mirrors existing vector sync behavior.
-3. On stale or missing graph index, request path serves via SQL fallback and schedules catch-up.
-4. Reindex is idempotent and safe to rerun.
-5. Index version metadata is tracked per project for staleness checks.
-
-Operational behaviors:
-1. Foreground requests never block on full reindex completion.
-2. Background job failures surface in health endpoints with actionable status.
-3. Reindex job can run incremental or full mode.
-4. Phase 1 note: scheduler task names and reindex enqueue path are implemented; write/edit/move/delete sync hooks still need explicit wiring.
-
-## MCP and CLI Surface
-
-New MCP tools:
-1. `graph_lineage`
-2. `graph_impact`
-3. `graph_health`
-4. `fcm_simulate`
-5. `fcm_rank_actions`
-6. `fcm_import_model`
-7. `fcm_export_model`
-
-CLI passthrough additions:
-1. `bm tool graph-lineage ...`
-2. `bm tool graph-impact ...`
-3. `bm tool graph-health ...`
-4. `bm tool fcm-simulate ...`
-5. `bm tool fcm-rank-actions ...`
-6. `bm tool fcm-import-model ...`
-7. `bm tool fcm-export-model ...`
-
-Output conventions:
-1. Default output is JSON for MCP and CLI.
-2. MCP supports optional `output_format="text"` for human-readable summaries.
-3. CLI remains JSON-first to keep agent integration deterministic.
-
-## Test Strategy (fast loop + gates)
-
-### Slice-by-slice loop
-
-For each vertical slice, implement in this order:
-1. API contract and schema.
-2. Typed MCP client.
-3. MCP tool passthrough.
-4. CLI passthrough.
-5. Focused tests for API/MCP/CLI.
-
-Fast checks per slice:
-1. Targeted `pytest` for changed API, MCP, and CLI modules.
-2. `just fast-check`.
-3. `just doctor`.
-4. `just test-graph-intel` for graph/FCM-only iteration loop.
-
-Milestone gates:
-1. SQLite unit and integration pass first.
-2. Selective Postgres parity tests for new graph and FCM contracts.
-3. Full `just check` before merge.
-
-### Required test cases and scenarios
-
-1. Casual user impact preview before note edit.
-2. Decision audit: lineage plus evidence references explain recommendation.
-3. Graph health deterministic output for fixed snapshot.
-4. Research flow: import model -> simulate -> rank -> export.
-5. Sparse and contradictory graph input degrades gracefully.
-6. Interop round-trip preserves node/edge counts and signed weights.
-7. Local and cloud parity on contract semantics and error model.
-8. Stale index fallback path returns valid response and schedules catch-up.
-
-## Rollout and Feature Flagging
-
-Rollout controls:
-1. Gate graph and FCM endpoints behind config flags first.
-2. Add entitlement enforcement after behavior and reliability stabilize.
-3. Keep existing tools and endpoints fully backward compatible.
-
-Suggested flags:
-1. `feature_graph_intelligence_enabled`
-2. `feature_fcm_enabled`
-3. `feature_graph_oxigraph_provider_enabled`
-4. `feature_graph_sql_fallback_enabled`
-
-Rollout sequence:
-1. Enable contract skeleton in dev.
-2. Enable graph features for internal alpha users.
-3. Enable Oxigraph provider with fallback-on by default.
-4. Enable FCM import/simulate/rank/export for research alpha users.
-5. Promote to Local+ beta when acceptance criteria are met.
-
-## Risks and Mitigations
-
-1. Risk: graph query complexity increases p95 latency.  
-Mitigation: strict query caps, fallback path, and performance budgets per endpoint.
-2. Risk: stale index produces confusing outputs.  
-Mitigation: explicit staleness checks, SQL fallback, and background catch-up scheduling.
-3. Risk: FCM recommendations appear opaque.  
-Mitigation: require evidence references, confidence fields, and deterministic simulation metadata.
-4. Risk: local/cloud contract drift.  
-Mitigation: shared schemas, contract tests, and parity checks in CI gates.
-5. Risk: integration surface grows faster than team can validate.  
-Mitigation: phase gates and vertical-slice completion before opening next phase.
-
-## Improvement Backlog (Post-Phase 1)
-
-1. Refactor `bm tool` graph/FCM commands into a dedicated CLI module to reduce `tool.py` size and improve maintainability.
-2. Consolidate repeated MCP text-formatting helpers for graph/FCM outputs.
-3. Replace deterministic placeholder graph behavior with SQL-backed lineage/impact/health implementations.
-4. Add explicit config/entitlement enforcement for graph/FCM endpoints and tools.
-5. Add performance telemetry and p95 reporting for graph and FCM routes.
-6. Add parity and degradation tests for stale-index fallback and contradictory/sparse inputs.
-
-## Acceptance Criteria
-
-1. All required sections in this document are complete with no unresolved decisions.
-2. API/interface contracts are implementation-ready with request, response, error, latency, and scale details.
-3. Architecture alignment is explicit: FastAPI logic core, MCP/CLI facades, shared local/cloud contracts.
-4. Delivery phases define concrete outputs and exit criteria.
-5. Test strategy includes tight iteration loop and milestone gates.
-6. Required scenario matrix is covered in test plan and mapped to implementation phases.
-7. Rollout plan includes feature flags and backward compatibility guarantees.
-8. An implementer can execute this plan without additional architecture clarification.
-
-## Assumptions and Defaults
-
-1. Config-flag gating first; entitlement wiring later.
-2. Graph-first vertical slices before deep FCM expansion.
-3. Atomic tools first; orchestration layer deferred.
-4. JSON-first contracts for agent usability.
-5. No breaking changes to existing `build_context` and `search_notes`.
-
-## Out of Scope
-
-1. Implementation details unrelated to graph/FCM delivery phases in this document.
-2. Migration execution.
-3. Pricing and positioning rewrites.
-4. Cloud infrastructure changes in this phase.

docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-MASTER.md

@@ -1,782 +0,0 @@
-# SPEC-LOCAL-GRAPH-INTELLIGENCE-MASTER: Local+ Graph Intelligence Blueprint
-
-**Status:** Draft (Iteration 2, Decision-Complete)  
-**Date:** 2026-03-05  
-**Owner:** Basic Memory  
-**Primary Audience:** Internal build team (Product, Engineering, GTM)  
-**Current Phase (2026-03-05):** Implementation Plan Phase 1 is complete; Phase 2 (SQL-backed graph logic) is the active engineering phase.  
-**Related Specs:**
-1. `/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE.md`
-2. `/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-TECHNICAL-ADDENDUM.md`
-3. `/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-IMPLEMENTATION-PLAN.md`
-
-Reading guide:
-1. Sections 1-5 define the business and product decisions.
-2. Sections 6-10 define architecture and interface contracts.
-3. Sections 11-14 define pricing, rollout, and decision gates for execution.
-
-## 1) Executive Thesis
-
-Basic Memory will ship **Local+ Graph Intelligence** as a premium local capability that upgrades the product from retrieval to decision support.
-
-Positioning statement:
-1. "Keep your local workflow. Add decision intelligence as complexity grows."
-2. The product sells safer decisions and explainable recommendations, not graph database mechanics.
-
-Locked thesis decisions:
-1. SQLite will remain the operational core.
-2. Markdown will remain source of truth.
-3. Graph and FCM indexes will be derived and rebuildable.
-4. Oxigraph/pyoxigraph will be the v1 graph index path.
-5. FCM simulation will run in a Python service layer.
-6. SurrealDB and FalkorDB will not be core dependencies in v1 due license-roadmap mismatch.
-7. Product messaging will sell outcomes (safer decisions, explainable recommendations), not database internals.
-
-## 2) Problem and Opportunity
-
-Current state after v0.19:
-1. Recursive SQL traversal can retrieve connected notes but becomes expensive and noisy after a few hops.
-2. Users still do manual synthesis for impact analysis, decision lineage, and contradiction resolution.
-3. Researchers need causal reasoning and scenario modeling, not only graph navigation.
-
-Opportunity:
-1. Deliver a premium local tier that materially improves decision quality while keeping data local.
-2. Create a bridge from knowledge graph navigation to causal simulation (FCM).
-3. Open a research-heavy market segment that values explainability and model interoperability.
-
-Business opportunity:
-1. Add a middle tier between free OSS and cloud subscription.
-2. Preserve an upgrade path to hosted collaboration for research teams later.
-3. Differentiate Basic Memory for research-grade workflows without forcing cloud adoption.
-
-## 3) User Segments and Jobs-to-be-Done
-
-| Segment | Primary Job-to-be-Done | Pain Today | Value Trigger |
-|---|---|---|---|
-| Casual local builder | Avoid breaking related notes when editing | Hidden dependencies and rework | Impact preview before edits |
-| Solo technical founder | Keep architecture and decision context coherent | Context overload and drift | Decision lineage + impact radius |
-| Research user | Model and test intervention strategies | No integrated causal simulation with notes | FCM simulation + action ranking |
-| Product/research lead | Synthesize evidence quickly across many docs | Fragmented understanding | Path exploration + priority briefs |
-
-## 4) Product Outcomes (not feature list)
-
-Local+ Graph Intelligence will optimize for these outcomes:
-1. **Change Safety:** users catch downstream impacts before they edit.
-2. **Decision Clarity:** users can explain why an answer or recommendation was produced.
-3. **Knowledge Health:** users keep larger graphs coherent with less manual audit work.
-4. **Research Leverage:** users run scenario-level reasoning tied to explicit evidence.
-
-Outcome metrics (for 30-day retained Local+ cohorts):
-1. Median time-to-understanding for complex topics decreases by at least 35% for active Local+ users.
-2. User-reported surprise side effects after note edits decrease by at least 30%.
-3. At least 60% of active Local+ users invoke graph intelligence features weekly.
-4. At least 40% of research-profile Local+ users invoke one FCM workflow weekly.
-
-## 5) Feature Set v1/v1.5/v2
-
-### v1 (post-v0.19 launch scope)
-
-Included:
-1. Decision Lineage
-2. Impact Radius
-3. Path Explorer (guided)
-4. Graph Health (orphans, stale-central nodes, overloaded hubs)
-5. CSV FCM import/export (nodes and edges)
-6. FCM simulation for explicit action scenarios
-7. FCM action ranking with evidence-linked rationale
-
-Excluded:
-1. Native Mental Modeler project format write support
-2. Team governance and shared model policy controls
-3. Cloud-only enhancements
-
-### v1.5
-
-Included:
-1. Contradiction Watch with reconciliation queue
-2. Priority Briefs (graph + FCM leverage summary)
-3. Stronger uncertainty propagation in FCM scoring
-4. Cloud execution optionality for heavy simulation jobs
-
-### v2
-
-Included:
-1. Team-shared model governance
-2. Hosted collaboration features for research teams
-3. Optional native model translators beyond CSV baseline
-
-Cut line policy:
-1. If a capability cannot meet explainability requirements, it moves to v1.5+.
-2. If a capability requires cloud to function, it cannot be marked v1.
-3. If a capability cannot meet local performance envelopes, it cannot be promoted into default workflows.
-
-## 6) Technical Architecture (Two-Graph Model)
-
-### High-level architecture
-
-```mermaid
-flowchart LR
-    A[Markdown Files Source of Truth] --> B[Parser + Sync Pipeline]
-    B --> C[SQLite Operational Store]
-    B --> D[Derived Knowledge Graph Index Oxigraph]
-    C --> E[Graph Intelligence Service]
-    D --> E
-    E --> F[Lineage Impact Path Health APIs]
-    C --> G[FCM Service Python]
-    D --> G
-    G --> H[Simulation Ranking Interop APIs]
-```
-
-### Two-graph model
-
-1. **Knowledge Graph (descriptive):** notes, decisions, concepts, and typed relations.
-2. **FCM Graph (causal):** signed weighted influence links between goals, drivers, risks, and interventions.
-
-### Core architectural decisions
-
-1. SQLite is authoritative for entities, observations, relations, metadata, embeddings, and project state.
-2. Oxigraph is a derived index for multi-hop graph traversal and graph-pattern retrieval.
-3. FCM calculations run in Python using explicit model state and deterministic numerical steps.
-4. Local mode runs fully offline.
-5. Cloud mode can execute the same contracts via adjunct services while Neon remains system of record.
-
-## 7) Backend Decision and Trade-Offs
-
-### Final recommendation
-
-Use this stack for v1:
-1. SQLite (existing): primary operational store.
-2. Oxigraph/pyoxigraph: derived knowledge graph index.
-3. Python FCM service: causal simulation and ranking.
-
-Decision rationale:
-1. This preserves local-first UX while enabling deeper traversal and causal simulation.
-2. This avoids restrictive licensing dependencies in the core product path.
-3. This keeps a clean cloud portability path where Neon remains the hosted system of record.
-
-### Trade-off matrix
-
-| Option | Strengths | Risks | Decision |
-|---|---|---|---|
-| SQLite + Oxigraph + Python FCM | Local-first, permissive licensing, clear service boundaries, cloud-portable | Requires translation layer for query ergonomics | **Adopt v1** |
-| Apache AGE on Postgres | SQL+graph in one engine, good cloud-side graph semantics | Neon extension support uncertainty, weaker local/cloud parity with SQLite local baseline | Defer |
-| SurrealDB | Strong integrated multi-model experience | BSL posture conflicts with future hosted/open strategy timing | Reject for v1 core |
-| FalkorDB | Graph performance and Redis ecosystem familiarity | SSPL posture conflicts with hosted/open strategy | Reject for v1 core |
-
-## 8) Public APIs / Interfaces
-
-All APIs are proposed MCP tool contracts for Local+ mode.
-
-### Common conventions
-
-1. `project` parameter is optional and follows existing Basic Memory project routing.
-2. Deterministic fields are reproducible with identical inputs and index state.
-3. Probabilistic fields are model-derived scores and include confidence metadata.
-4. Error model uses structured codes and fail-fast behavior.
-
-Shared error codes:
-1. `INVALID_ARGUMENT`
-2. `NOT_FOUND`
-3. `MODEL_INVALID`
-4. `INDEX_NOT_READY`
-5. `RESOURCE_LIMIT_EXCEEDED`
-6. `INTERNAL_ERROR`
-
----
-
-### 8.1 `graph_lineage(start, goal?)`
-
-**Input schema:**
-```json
-{
-  "start": "string (required, permalink or memory URL)",
-  "goal": "string (optional, concept or decision target)",
-  "max_hops": "integer (optional, default 4, range 1-6)",
-  "relation_filters": ["string"],
-  "project": "string (optional)"
-}
-```
-
-**Output schema:**
-```json
-{
-  "root": {"id": "string", "title": "string", "permalink": "string"},
-  "paths": [
-    {
-      "path_id": "string",
-      "nodes": [{"id": "string", "title": "string"}],
-      "edges": [{"relation": "string", "direction": "outgoing|incoming"}],
-      "deterministic_path_score": 0.0,
-      "confidence": 0.0,
-      "evidence_refs": ["memory://..."]
-    }
-  ],
-  "generated_at": "RFC3339"
-}
-```
-
-**Deterministic fields:** root, nodes, edges, deterministic path score, generated timestamp.  
-**Probabilistic fields:** confidence.
-
-**Latency target:** p95 <= 450ms for `max_hops<=4`, graph envelope up to 50k nodes / 300k edges.
-
-**Scale envelope:**
-1. Tested local baseline: 50k nodes, 300k edges.
-2. Expected degradation: path expansion can exceed latency target when candidate paths > 20k.
-
----
-
-### 8.2 `graph_impact(target, horizon, relation_filters?)`
-
-**Input schema:**
-```json
-{
-  "target": "string (required)",
-  "horizon": "integer (required, range 1-4)",
-  "relation_filters": ["string"],
-  "include_reasons": "boolean (default true)",
-  "project": "string (optional)"
-}
-```
-
-**Output schema:**
-```json
-{
-  "target": {"id": "string", "title": "string"},
-  "affected": [
-    {
-      "id": "string",
-      "title": "string",
-      "distance": 2,
-      "impact_score": 0.0,
-      "confidence": 0.0,
-      "reasons": ["string"]
-    }
-  ],
-  "summary": {"total_considered": 0, "total_returned": 0}
-}
-```
-
-**Deterministic fields:** membership, distance, summary counts.  
-**Probabilistic fields:** impact score, confidence.
-
-**Latency target:** p95 <= 650ms for `horizon<=3` under baseline envelope.
-
-**Scale envelope:**
-1. `affected` default cap: 200 items.
-2. Hard cap: 1000 items with pagination token.
-
----
-
-### 8.3 `graph_health(scope?, timeframe?)`
-
-**Input schema:**
-```json
-{
-  "scope": "string (optional, directory prefix or project-wide)",
-  "timeframe": "string (optional, e.g. 30d, 90d)",
-  "project": "string (optional)"
-}
-```
-
-**Output schema:**
-```json
-{
-  "metrics": {
-    "orphan_rate": 0.0,
-    "stale_central_nodes": 0,
-    "overloaded_hubs": 0,
-    "contradiction_candidates": 0
-  },
-  "issues": [
-    {
-      "issue_type": "orphan|stale_central|overloaded_hub|contradiction_candidate",
-      "entity_id": "string",
-      "severity": "low|medium|high",
-      "reason": "string",
-      "suggested_action": "string"
-    }
-  ],
-  "computed_at": "RFC3339"
-}
-```
-
-**Deterministic fields:** metrics and issue list membership for a fixed graph snapshot.  
-**Probabilistic fields:** contradiction candidate confidence when present.
-
-**Latency target:** p95 <= 1500ms project-wide; <= 700ms for scoped directory mode.
-
-**Scale envelope:** project-wide scans tested to 50k nodes.
-
----
-
-### 8.4 `fcm_simulate(actions, scenario?, clamp_rules?)`
-
-**Input schema:**
-```json
-{
-  "actions": [
-    {"node_id": "string", "delta": 0.2}
-  ],
-  "scenario": {
-    "steps": 12,
-    "activation": "tanh|sigmoid|bounded_linear",
-    "decay": 0.05
-  },
-  "clamp_rules": [
-    {"node_id": "string", "min": -1.0, "max": 1.0}
-  ],
-  "project": "string (optional)"
-}
-```
-
-**Output schema:**
-```json
-{
-  "baseline": [{"node_id": "string", "state": 0.12}],
-  "projected": [{"node_id": "string", "state": 0.43}],
-  "deltas": [{"node_id": "string", "delta": 0.31}],
-  "stability": {
-    "converged": true,
-    "iterations_used": 9,
-    "residual": 0.002
-  },
-  "confidence": 0.0,
-  "explanations": [
-    {"node_id": "string", "top_influencers": [{"source": "string", "weight": 0.7}]}
-  ]
-}
-```
-
-**Deterministic fields:** baseline, projected, deltas, convergence metadata for fixed model and parameters.  
-**Probabilistic fields:** confidence (derived from edge confidence and evidence coverage).
-
-**Latency target:** p95 <= 1000ms for up to 500 nodes / 5000 edges and <=12 steps.
-
-**Scale envelope:**
-1. Soft limit: 2000 nodes / 20000 edges.
-2. Over soft limit: return `RESOURCE_LIMIT_EXCEEDED` with remediation guidance.
-
----
-
-### 8.5 `fcm_rank_actions(goal, constraints?, top_k?)`
-
-**Input schema:**
-```json
-{
-  "goal": "string (required node_id)",
-  "constraints": {
-    "max_negative_impact": 0.25,
-    "required_tags": ["string"],
-    "disallowed_nodes": ["string"]
-  },
-  "top_k": "integer (default 10, range 1-25)",
-  "project": "string (optional)"
-}
-```
-
-**Output schema:**
-```json
-{
-  "goal": {"node_id": "string", "label": "string"},
-  "recommendations": [
-    {
-      "action_node_id": "string",
-      "expected_goal_delta": 0.0,
-      "risk_penalty": 0.0,
-      "net_score": 0.0,
-      "confidence": 0.0,
-      "rationale": ["string"],
-      "evidence_refs": ["memory://..."]
-    }
-  ]
-}
-```
-
-**Deterministic fields:** candidate action set, constraints compliance.  
-**Probabilistic fields:** expected goal delta, risk penalty, net score, confidence.
-
-**Latency target:** p95 <= 1500ms for top 10 from up to 100 candidate actions.
-
-**Scale envelope:**
-1. Candidate actions hard cap: 1000.
-2. For larger sets, require pre-filtering via tags/scope.
-
----
-
-### 8.6 `fcm_import_model(source, format)`
-
-**Input schema:**
-```json
-{
-  "source": "string (required path or URI)",
-  "format": "csv_bundle_v1 (required)",
-  "merge_mode": "replace|upsert (default upsert)",
-  "project": "string (optional)"
-}
-```
-
-**Output schema:**
-```json
-{
-  "import_id": "string",
-  "nodes_loaded": 0,
-  "edges_loaded": 0,
-  "warnings": ["string"],
-  "errors": ["string"]
-}
-```
-
-**Deterministic fields:** load counts and validation results.  
-**Probabilistic fields:** none.
-
-**Latency target:** p95 <= 2500ms for 10k edges CSV bundle.
-
-**Scale envelope:**
-1. Maximum CSV rows per import: 250k.
-2. Above limit returns `RESOURCE_LIMIT_EXCEEDED`.
-
----
-
-### 8.7 `fcm_export_model(format, selection?)`
-
-**Input schema:**
-```json
-{
-  "format": "csv_bundle_v1 (required)",
-  "selection": {
-    "scope": "all|tag|subgraph",
-    "tag": "string (optional)",
-    "seed_nodes": ["string"]
-  },
-  "project": "string (optional)"
-}
-```
-
-**Output schema:**
-```json
-{
-  "export_id": "string",
-  "format": "csv_bundle_v1",
-  "files": [
-    {"name": "nodes.csv", "path": "string"},
-    {"name": "edges.csv", "path": "string"}
-  ],
-  "node_count": 0,
-  "edge_count": 0
-}
-```
-
-**Deterministic fields:** file set and row counts for fixed selection.  
-**Probabilistic fields:** none.
-
-**Latency target:** p95 <= 1800ms for 50k edges export.
-
-**Scale envelope:**
-1. Max export rows: 500k total.
-2. Pagination or scoped export required above cap.
-
-## 9) Data Model and Storage Boundaries
-
-### 9.1 Knowledge graph schema (descriptive)
-
-`KnowledgeNode`:
-1. `id: str`
-2. `kind: note|decision|spec|concept|person|project`
-3. `title: str`
-4. `permalink: str`
-5. `tags: list[str]`
-6. `updated_at: datetime`
-
-`KnowledgeEdge`:
-1. `id: str`
-2. `src_id: str`
-3. `dst_id: str`
-4. `relation: str`
-5. `directionality: directed|bidirectional`
-6. `evidence_refs: list[str]`
-7. `confidence: float [0,1]`
-8. `updated_at: datetime`
-
-### 9.2 FCM schema (causal signed weighted)
-
-`FCMNode`:
-1. `id: str`
-2. `label: str`
-3. `node_type: goal|driver|risk|intervention|context`
-4. `state: float [-1,1]`
-5. `clamp_min: float`
-6. `clamp_max: float`
-7. `metadata: map`
-
-`FCMEdge`:
-1. `id: str`
-2. `source_id: str`
-3. `target_id: str`
-4. `weight: float [-1,1]`
-5. `confidence: float [0,1]`
-6. `time_decay: float [0,1]`
-7. `evidence_refs: list[str]`
-8. `updated_at: datetime`
-
-### 9.3 Provenance model
-
-`ProvenanceRecord`:
-1. `entity_id: str`
-2. `evidence_refs: list[str]`
-3. `confidence: float [0,1]`
-4. `updated_at: datetime`
-5. `source_type: extracted|user_authored|imported`
-
-### 9.4 Scenario model
-
-`Scenario`:
-1. `id: str`
-2. `name: str`
-3. `interventions: list[{node_id, delta}]`
-4. `constraints: list[{node_id, min, max}]`
-5. `steps: int`
-6. `activation: tanh|sigmoid|bounded_linear`
-7. `created_at: datetime`
-8. `created_by: str`
-
-`ScenarioResult`:
-1. `scenario_id: str`
-2. `converged: bool`
-3. `iterations_used: int`
-4. `residual: float`
-5. `goal_deltas: list[{node_id, delta}]`
-6. `confidence: float [0,1]`
-
-### 9.5 Storage boundaries
-
-| Layer | System of Record | Purpose | Rebuildable |
-|---|---|---|---|
-| Markdown files | File system | Canonical knowledge content | No |
-| SQLite entities/relations/embeddings | SQLite | Operational queries and project state | Yes (from markdown + embedding pipeline) |
-| Knowledge graph triples | Oxigraph | Fast graph traversal and pattern queries | Yes |
-| FCM model and snapshots | SQLite + optional artifacts | Causal model state and scenario history | Yes (from imports and authored model definitions) |
-
-## 10) Mental Modeler Interoperability
-
-### v1 interoperability contract
-
-Format: `csv_bundle_v1`
-1. `nodes.csv`
-2. `edges.csv`
-3. Optional `scenarios.csv`
-
-`nodes.csv` required columns:
-1. `node_id`
-2. `label`
-3. `node_type`
-4. `state`
-5. `clamp_min`
-6. `clamp_max`
-
-`edges.csv` required columns:
-1. `edge_id`
-2. `source_id`
-3. `target_id`
-4. `weight`
-5. `confidence`
-6. `evidence_refs` (semicolon-delimited)
-
-### Import rules
-
-1. Missing required columns fail with `MODEL_INVALID`.
-2. Unknown node types fail fast.
-3. Weight and confidence ranges are strictly validated.
-4. Import returns warnings for dangling evidence references.
-
-### Export rules
-
-1. Preserve stable IDs for round-trip compatibility.
-2. Preserve signed weights exactly.
-3. Preserve confidence values exactly.
-4. Non-portable metadata is emitted to `metadata.json` sidecar when present.
-
-### Native file translators
-
-1. Native project-format translation is deferred to v2.
-2. CSV remains the guaranteed compatibility baseline in v1 and v1.5.
-
-## 11) Pricing and Packaging
-
-### Tier structure
-
-| Tier | Price Monthly | Price Annual | Beta Price (25% off) | Target Persona | Core Value |
-|---|---:|---:|---:|---|---|
-| OSS Local | $0 | $0 | $0 | Casual local users | Retrieval and memory basics |
-| Local+ Graph Intelligence | $9 | $90 | $6.75 monthly / $67.50 annual | Founders, consultants, researchers | Safer changes + explainable graph + FCM simulation |
-| Cloud Pro (current anchor) | $19 | $190 | $14.25 monthly / $142.50 annual | Users who need hosted sync and cloud workflows | Managed cloud + sync + collaboration path |
-
-Pricing principles:
-1. Local+ is intentionally priced between free OSS and cloud to capture users who need deeper intelligence but not hosted sync.
-2. Cloud Pro remains the hosted convenience anchor and future collaboration path.
-3. Local+ must stand on standalone local value and cannot depend on cloud features.
-
-### Feature gate mapping
-
-| Capability | OSS Local | Local+ | Cloud Pro |
-|---|---|---|---|
-| Search and basic context tools | Yes | Yes | Yes |
-| Decision Lineage | No | Yes | Yes |
-| Impact Radius | No | Yes | Yes |
-| Graph Health | No | Yes | Yes |
-| FCM simulate + rank | No | Yes | Yes |
-| CSV model import/export | No | Yes | Yes |
-| Hosted collaboration controls | No | No | Future add-on |
-
-### Packaging decisions
-
-1. Local+ remains fully local-capable and does not require cloud auth to run.
-2. Cloud Pro remains the hosted convenience and collaboration anchor.
-3. Future hosted research add-on will layer on Cloud Pro after v2 readiness.
-
-## 12) Rollout Strategy
-
-### 12.1 Document production iterations (locked)
-
-Iteration 1 (draft complete):
-1. Complete all 15 sections in one pass.
-2. Include v1/v1.5/v2 cut lines.
-3. Include pricing and scenario definitions.
-4. Ensure no placeholders.
-
-Iteration 2 (hardening and decision lock):
-1. Resolve cross-section contradictions.
-2. Convert uncertain language to locked decisions.
-3. Add measurable acceptance criteria and risk owners.
-4. Finalize execution-ready API contracts.
-
-### 12.2 Product rollout phases
-
-Phase A: Foundation release (v1)
-1. Graph lineage, impact, health.
-2. CSV model import/export.
-3. FCM simulation and ranking.
-4. Advanced mode UX gating for research-grade controls.
-
-Phase B: Quality and confidence (v1.5)
-1. Contradiction Watch.
-2. Priority Briefs.
-3. Improved uncertainty propagation.
-4. Confidence calibration pass using real-world model feedback.
-
-Phase C: Team expansion (v2)
-1. Hosted team governance.
-2. Shared model controls.
-3. Extended translator support.
-
-### 12.3 Go/No-Go release gates
-
-Gate to ship v1 default workflows:
-1. p95 latency targets are met within the declared scale envelopes.
-2. Scenario round-trip fidelity tests pass for CSV import/export.
-3. Every recommendation and simulation path exposes evidence references and confidence.
-
-Gate to ship v1.5:
-1. Contradiction Watch precision is acceptable for default-on use.
-2. Confidence calibration reduces false-confidence reports in user testing.
-
-Gate to ship v2 team features:
-1. Clear willingness-to-pay signal from team and research buyers.
-2. Cloud execution path preserves local-cloud semantic parity for core contracts.
-
-## 13) Risks, Counterarguments, and Mitigations
-
-| Risk | Counterargument | Severity | Likelihood | Mitigation | Owner |
-|---|---|---|---|---|---|
-| "This is just better search" | Positioning can collapse into technical jargon | High | Medium | Lead with decision safety and explainability outcomes in product copy and onboarding | Product Lead |
-| FCM feels opaque or invented | Users distrust black-box scoring | High | Medium | Require evidence refs and confidence disclosure on every recommendation | Applied AI Lead |
-| Local performance regressions | Multi-hop and simulation can feel slow on laptops | Medium | Medium | Enforce envelopes, caps, and fail-fast limit errors with guidance | Engineering Lead |
-| Research features overwhelm casual users | UX complexity can reduce adoption | Medium | High | Default to guided flows and hide advanced controls behind explicit advanced mode | Design Lead |
-| License/roadmap conflict if backend changes | Later swap to restrictive engines creates GTM risk | High | Low | Lock permissive v1 stack and require leadership sign-off for any license-restricted dependency | Product + Legal |
-| Interop mismatch with external tools | Round-trip drift harms trust with researchers | Medium | Medium | Validate node and edge parity in import/export tests and version interop schema | Integrations Lead |
-| Pricing confusion between Local+ and Cloud Pro | Buyers may not understand which tier fits | Medium | Medium | Publish explicit tier comparison focused on local intelligence vs hosted collaboration | GTM Lead |
-
-## 14) Acceptance Criteria
-
-### 14.1 Document acceptance criteria
-
-1. Product, technical, and pricing decisions are explicit and unambiguous.
-2. API contracts include input/output schemas, error models, deterministic versus probabilistic fields, and performance envelopes.
-3. v1/v1.5/v2 cut lines are explicit and consistent.
-4. Risk register includes severity, likelihood, owner, and mitigation.
-5. Document can be handed to implementation without additional architecture decisions.
-6. Leadership can use this document directly for pricing and positioning decisions.
-
-### 14.2 Product acceptance criteria for v1 delivery
-
-1. `graph_lineage`, `graph_impact`, `graph_health`, `fcm_simulate`, `fcm_rank_actions`, `fcm_import_model`, and `fcm_export_model` are available as Local+ contracts.
-2. Local mode executes all v1 contracts without cloud dependency.
-3. API p95 latency targets are met within defined scale envelopes.
-4. Every ranked or simulated output includes evidence-linked rationale and confidence.
-5. CSV round-trip preserves node count, edge count, and signed weights exactly.
-
-### 14.3 Scenario test matrix (required)
-
-1. **Casual local user impact check**
-Expected pass:
-`graph_impact` returns ranked affected notes with reasons before a note edit.
-
-2. **Research workflow simulation**
-Expected pass:
-User imports a model bundle, runs `fcm_simulate`, and receives converged deltas and rationale.
-
-3. **Decision audit traceability**
-Expected pass:
-`graph_lineage` returns path and evidence references that explain recommendation origin.
-
-4. **Cloud and local parity**
-Expected pass:
-Identical query inputs return semantically equivalent outputs in local and cloud modes with local fallback behavior when cloud is unavailable.
-
-5. **Sparse or contradictory graph behavior**
-Expected pass:
-System degrades gracefully with explicit uncertainty and does not fabricate high-confidence recommendations.
-
-6. **Interop round-trip fidelity**
-Expected pass:
-`fcm_export_model` then `fcm_import_model` preserves node and edge counts and signed weights without mutation.
-
-## 15) Appendix (license notes, terminology, examples)
-
-### 15.1 License notes (verified 2026-03-05)
-
-1. SurrealDB core licensing is published under BSL 1.1 with DBaaS-related restrictions in its conversion window.
-2. FalkorDB is published under SSPLv1.
-3. pyoxigraph is dual-licensed Apache-2.0 or MIT.
-4. Neon extension catalog currently does not list Apache AGE as a supported extension.
-
-These notes support the v1 dependency decisions in this document.
-
-### 15.2 Terminology
-
-1. **Knowledge graph:** descriptive relation graph derived from markdown knowledge.
-2. **FCM:** fuzzy cognitive model with signed weighted causal edges.
-3. **Deterministic field:** reproducible output field from fixed input and fixed model/index snapshot.
-4. **Probabilistic field:** score influenced by confidence weights and model uncertainty.
-
-### 15.3 Assumptions and defaults
-
-1. Markdown remains source of truth.
-2. SQLite remains mandatory baseline.
-3. Graph and FCM capabilities are premium Local+ features, not OSS defaults.
-4. Research-heavy features are advanced mode, while mainstream UX stays guided.
-5. Mental Modeler interoperability starts with CSV contract first; native translator support is deferred.
-
-### 15.4 Out of scope for this document
-
-1. Implementation code changes.
-2. Database migrations.
-3. Cloud infrastructure edits.
-4. Full instrumentation pilot plan as the primary artifact.
-
-### 15.5 External references
-
-1. [SurrealDB licensing](https://surrealdb.com/license)
-2. [FalkorDB licensing](https://docs.falkordb.com/References/license.html)
-3. [pyoxigraph package and license](https://pypi.org/project/pyoxigraph/)
-4. [Neon Postgres extension catalog](https://neon.com/docs/extensions/pg-extensions)

docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-TECHNICAL-ADDENDUM.md

@@ -1,299 +0,0 @@
-# SPEC-LOCAL-GRAPH-INTELLIGENCE: Technical Addendum (Graph + FCM)
-
-**Status:** Draft  
-**Date:** 2026-03-05  
-**Owner:** Basic Memory
-**Current Phase (2026-03-05):** Contract skeleton implementation is complete; next active phase is SQL-backed graph capabilities.
-
-Related product spec:
-`/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE.md`
-
-Related execution spec:
-`/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-IMPLEMENTATION-PLAN.md`
-
-## Why This Addendum Exists
-
-The product spec defines user value. This addendum defines the technical shape that can deliver that value without
-breaking local-first principles.
-
-This addendum also introduces a second graph layer:
-
-1. Knowledge graph for relationships between notes, entities, and decisions.
-2. Fuzzy Cognitive Model (FCM) graph for weighted causal reasoning over actions and outcomes.
-
-Both are derived from markdown and optional user-provided models.
-
-## Strategic Reality Check
-
-This is a strong idea if we stage it correctly.
-
-It is not a pipe dream if we avoid one trap: building a big "graph platform" before proving users repeatedly use
-decision simulation workflows.
-
-The correct strategy is:
-
-1. Launch high-precision graph insights first.
-2. Add FCM scoring where it changes user behavior (not as a novelty dashboard).
-3. Expand to hosted/team workflows only after local usage proves repeat value.
-
-## Constraints and Design Principles
-
-1. SQLite remains the operational source for entities, observations, relations, and embeddings.
-2. Markdown remains source of truth.
-3. Graph indexes are derived, rebuildable, and disposable.
-4. Premium local mode must run fully offline.
-5. Cloud deployment should support both single-tenant and SaaS later.
-6. Avoid licenses that constrain hosted/open-source strategy.
-
-## Backend Recommendation
-
-### Primary Recommendation
-
-Use a dual-store architecture:
-
-1. SQLite (existing): operational data, metadata filters, embeddings, and most retrieval.
-2. Oxigraph/pyoxigraph (new): derived graph index for graph traversal and graph-pattern queries.
-3. Python simulation layer (new): FCM state propagation, scenario runs, and decision scoring.
-
-Why this is the best fit:
-
-1. Permissive licensing profile.
-2. Works locally with low footprint.
-3. Cloud-compatible as sidecar service while keeping Neon Postgres as core cloud store.
-4. Clear boundary between graph query and numeric simulation concerns.
-
-### Candidate Trade-Offs
-
-#### Oxigraph/pyoxigraph
-
-Pros:
-
-1. Lightweight local embedding.
-2. Good fit for derived-index strategy.
-3. Strong path for standards-based graph representation.
-
-Cons:
-
-1. SPARQL fluency is less common than SQL/Cypher.
-2. Requires a translation layer so product features are not query-language-coupled.
-
-#### Apache AGE (Postgres extension)
-
-Pros:
-
-1. SQL + graph in one engine.
-2. Attractive for cloud-side graph operations.
-
-Cons:
-
-1. Neon support is uncertain for this extension.
-2. Local/cloud parity is harder if local uses SQLite.
-
-#### SurrealDB / FalkorDB
-
-Pros:
-
-1. Strong graph-oriented developer experience.
-
-Cons:
-
-1. License posture is misaligned with a future hosted/open-source roadmap unless commercial terms are accepted.
-
-Decision:
-Do not make these core dependencies for v1 of Local+ Graph Intelligence.
-
-## Two-Graph Model
-
-### A) Knowledge Graph (Descriptive)
-
-Node examples:
-
-1. Note
-2. Decision
-3. Spec
-4. Person
-5. Project
-6. Concept
-
-Edge examples:
-
-1. `depends_on`
-2. `informed_by`
-3. `contradicts`
-4. `supports`
-5. `implements`
-6. `derived_from`
-
-Purpose:
-Power navigation, lineage, path explanation, impact radius, and health checks.
-
-### B) FCM Graph (Causal, Signed, Weighted)
-
-Node examples:
-
-1. Goal: "Reduce regressions"
-2. Driver: "Test coverage"
-3. Risk: "Scope creep"
-4. Intervention: "Add review gate"
-5. Context variable: "Team bandwidth"
-
-Edge attributes:
-
-1. `weight` in [-1.0, 1.0]
-2. `confidence` in [0.0, 1.0]
-3. `evidence_refs` (links to notes/specs)
-4. `time_decay` (optional)
-
-Purpose:
-Power scenario simulation and action ranking, not generic retrieval.
-
-## Premium Feature Mapping to Architecture
-
-### Decision Lineage
-
-Backed by:
-
-1. Knowledge graph path queries.
-2. Evidence references stored on edges.
-
-### Impact Radius
-
-Backed by:
-
-1. Multi-hop neighborhood expansion with relation-type weights.
-2. Risk ranking using centrality + recency + confidence.
-
-### Contradiction Watch
-
-Backed by:
-
-1. Candidate contradiction edges.
-2. Confidence-scored reconciliation queue.
-
-### Priority Briefs
-
-Backed by:
-
-1. Health metrics (orphan rate, stale-central nodes, unresolved contradictions).
-2. Optional FCM "top leverage actions" summary.
-
-### New Premium Feature: Action Simulator
-
-Backed by:
-
-1. FCM scenario runs over selected action nodes.
-2. Ranked interventions with expected positive/negative downstream effects.
-3. Explicit rationale graph for every recommendation.
-
-## Mental Modeler Interop Plan
-
-Goal:
-Make Basic Memory the AI-enabled operating layer around existing researcher workflows, not a replacement for their tools.
-
-Interoperability phases:
-
-1. Import/export edge lists and node tables via CSV as the baseline interchange.
-2. Preserve concept IDs and metadata so round-trips remain stable.
-3. Add translator support for native model files if/when schema contracts are validated with partner data.
-
-Validation requirement:
-
-1. Round-trip tests must preserve node count, edge count, and signed weights.
-2. Confidence/evidence metadata may be Basic Memory extensions and should degrade gracefully when exported.
-
-## Suggested Tool/API Surface (Product-Facing)
-
-1. `graph_lineage(start, goal?)`  
-   Returns explainable evidence paths.
-2. `graph_impact(target, horizon=2..4)`  
-   Returns ranked affected nodes with reasons.
-3. `graph_health()`  
-   Returns actionable graph quality issues.
-4. `fcm_simulate(actions, scenario?)`  
-   Returns projected effects and uncertainty.
-5. `fcm_rank_actions(goal, constraints?)`  
-   Returns top candidate actions with trade-offs.
-6. `fcm_import_model(source)` / `fcm_export_model(format)`  
-   Handles interop with external cognitive mapping workflows.
-
-## Local and Cloud Deployment Shape
-
-### Local (Primary)
-
-1. SQLite + local embeddings.
-2. Oxigraph as local sidecar/index library.
-3. FCM simulation in process.
-
-### Cloud (Future-Compatible)
-
-1. Neon Postgres remains system of record in hosted mode.
-2. Graph index service runs per tenant or shared multi-tenant with strict tenancy boundaries.
-3. FCM simulation service can run stateless workers reading graph snapshots.
-
-Principle:
-Do not require cloud to run premium local features.
-
-## Rollout Plan With Go/No-Go Gates
-
-### Phase 0: Proof of Utility (4-6 weeks)
-
-Deliver:
-
-1. Decision Lineage
-2. Impact Radius
-3. CSV FCM import + `fcm_simulate` prototype
-
-Gate to continue:
-
-1. Repeated weekly usage by pilot users.
-2. Users report changed decisions, not just curiosity clicks.
-
-### Phase 1: Productized Local+ Beta
-
-Deliver:
-
-1. Graph health workflow
-2. Contradiction Watch
-3. Action ranking with explicit rationale
-
-Gate to continue:
-
-1. Retention of graph features after first month.
-2. Measured reduction in "surprise side effects" after edits.
-
-### Phase 2: Hosted Expansion
-
-Deliver:
-
-1. Optional cloud execution for heavy simulations.
-2. Team-shared model governance.
-
-Gate to continue:
-
-1. Clear willingness to pay for hosted collaboration.
-
-## Risks and Mitigations
-
-Risk: FCM outputs feel "made up."  
-Mitigation: Require evidence links and confidence scoring in every recommendation.
-
-Risk: Research-heavy feature alienates casual users.  
-Mitigation: Keep FCM features in an advanced mode; default to concise guidance workflows.
-
-Risk: Overengineering early graph stack.  
-Mitigation: Keep derived-index architecture and strict phase gates tied to behavior change.
-
-Risk: Interop friction with external tooling.  
-Mitigation: Start with transparent CSV contract and strict round-trip validation.
-
-## Candid Recommendation
-
-Pursue this. It is a high-upside differentiation path for Local+ if executed with staged validation.
-
-The key is to sell outcomes:
-
-1. "Safer decisions"
-2. "Explainable recommendations"
-3. "Faster synthesis for complex research"
-
-Avoid selling "graph DB" as the product. That is implementation detail.

docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE.md

@@ -1,262 +0,0 @@
-# SPEC-LOCAL-GRAPH-INTELLIGENCE: Premium Local Graph Intelligence
-
-**Status:** Draft  
-**Date:** 2026-03-05  
-**Owner:** Basic Memory
-**Current Phase (2026-03-05):** Phase 1 contract foundation shipped; engineering is now executing SQL-backed Phase 2 graph logic.
-
-Companion technical addendum:
-`/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-TECHNICAL-ADDENDUM.md`
-
-## Summary
-
-Add a premium local feature that turns Basic Memory from "search and recall" into "explain and guide."
-
-The value is not a new database. The value is better decisions for local users:
-
-1. Understand why something matters.
-2. See what will be affected before making a change.
-3. Detect weak spots in the knowledge base early.
-4. Navigate complex knowledge intentionally instead of loading everything.
-
-This feature is additive. Existing local workflows remain intact.
-
-## Positioning
-
-Core message:
-"Your notes do more than store knowledge. They reveal consequences, lineage, and blind spots."
-
-Local user promise:
-
-1. Keep files local.
-2. Keep markdown as source of truth.
-3. Get advanced graph intelligence as an opt-in premium capability.
-
-## Problem
-
-Today, deep graph navigation is possible but often expensive in context size and hard to steer for complex questions.
-Users can find information, but they still do manual synthesis to answer:
-
-1. What changed because of this note?
-2. Why did we decide this?
-3. What might break if I update this?
-4. Which parts of the graph are stale, isolated, or contradictory?
-
-The cost is time, cognitive load, and missed risk.
-
-## Goals
-
-1. Provide clear, explainable graph insights that users can act on.
-2. Make deep navigation feel guided, not overwhelming.
-3. Help users prevent mistakes before they happen.
-4. Create premium local value that is easy to understand and justify.
-5. Keep feature behavior transparent and trustworthy.
-
-## Non-Goals
-
-1. Replacing SQLite as the primary operational store.
-2. Changing markdown as source of truth.
-3. Forcing users to learn graph query languages.
-4. Building a cloud-only feature set.
-5. Turning Basic Memory into an enterprise BI product.
-
-## Product Frame: From Retrieval to Reasoning
-
-The feature should be framed as a shift in user outcome:
-
-1. Retrieval: "Find me the note."
-2. Reasoning: "Show me the path, impact, and confidence around this note."
-
-This is the main narrative upgrade for premium local users.
-
-## Premium Value Pillars
-
-### 1) Decision Confidence
-
-Users can see decision lineage:
-
-1. What evidence supported a decision.
-2. Which notes/specs informed it.
-3. How that decision evolved over time.
-
-### 2) Change Safety
-
-Users can run impact-aware workflows:
-
-1. Estimate blast radius before editing.
-2. Surface downstream dependencies.
-3. Prioritize what to review first.
-
-### 3) Knowledge Quality
-
-Users can maintain graph health:
-
-1. Detect orphaned notes.
-2. Detect overloaded hub notes.
-3. Detect stale but high-centrality notes.
-4. Detect likely contradictions.
-
-### 4) Guided Navigation
-
-Users can explore deeper relationships without context explosion:
-
-1. Follow promising branches.
-2. Stop when confidence is sufficient.
-3. Avoid "load everything and hope."
-
-## Feature Catalog (Value-First)
-
-### A. Decision Lineage
-
-What users get:
-
-1. A clear "why chain" for important conclusions.
-2. Traceable connections to supporting notes.
-3. Better handoffs and historical understanding.
-
-### B. Impact Radius
-
-What users get:
-
-1. A ranked list of likely affected notes before edits.
-2. Safer refactors for docs, plans, and architecture.
-3. Reduced accidental drift and inconsistency.
-
-### C. Knowledge Health Dashboard
-
-What users get:
-
-1. Weekly health signals for the graph.
-2. Actionable cleanup targets.
-3. Better long-term memory quality with less manual auditing.
-
-### D. Path Explorer
-
-What users get:
-
-1. "Show me how A connects to B" style explanations.
-2. Multiple candidate paths with confidence cues.
-3. Better discovery across large note collections.
-
-### E. Contradiction Watch
-
-What users get:
-
-1. Early warnings for conflicting statements.
-2. Suggested reconciliation workflow.
-3. Higher trust in the knowledge base.
-
-### F. Priority Briefs
-
-What users get:
-
-1. Periodic "what matters now" graph summaries.
-2. Focused recommendations, not noisy activity dumps.
-3. Better focus for solo builders and small teams.
-
-## User Personas and Why They Pay
-
-### Solo Technical Founder
-
-Pain:
-Cannot hold full architecture and decision history in working memory.
-
-Premium value:
-Impact Radius + Decision Lineage prevent rework and regressions.
-
-### Product/Research Lead
-
-Pain:
-Knowledge is fragmented across specs, notes, and decisions.
-
-Premium value:
-Path Explorer + Priority Briefs compress synthesis time.
-
-### Consultant/Fractional Operator
-
-Pain:
-Frequent context switching across domains and clients.
-
-Premium value:
-Knowledge Health + Decision Lineage speed onboarding and reporting.
-
-## Packaging Direction
-
-Suggested packaging:
-
-1. OSS Local: existing search + context tools.
-2. Local+ Graph Intelligence: advanced graph insight features listed above.
-3. Future Team Add-On: shared policies, shared graph health views, shared lineage views.
-
-Core upsell line:
-"Keep your local workflow. Add graph intelligence when complexity grows."
-
-## Experience Principles
-
-1. Explainability first.
-Every advanced result should show "why this was suggested."
-
-2. Actionability over novelty.
-Insights should lead to concrete next steps, not abstract charts.
-
-3. Progressive disclosure.
-Start with concise summaries, expand on demand.
-
-4. Deterministic where possible.
-Users should trust repeated runs of the same workflow.
-
-5. Respect local-first expectations.
-No surprise cloud dependency in premium local mode.
-
-## Success Criteria (Product)
-
-1. Users can describe the benefit in one sentence:
-"It shows me what matters and what breaks before I change things."
-2. Premium users report lower time-to-understanding for complex topics.
-3. Premium users report fewer "surprise side effects" after edits.
-4. Premium users keep larger knowledge graphs healthy with less manual effort.
-5. Feature adoption is driven by outcomes, not by curiosity-only usage.
-
-## Risks and Mitigations
-
-Risk: Feature sounds like "just better search."  
-Mitigation: Lead messaging with decision confidence and change safety, not traversal depth.
-
-Risk: Feature feels too advanced for normal users.  
-Mitigation: Package as guided insights and reports, not as a query language.
-
-Risk: Insight quality feels noisy.  
-Mitigation: Focus launch scope on high-precision insight types and transparent rationale.
-
-Risk: Value is hard to prove.  
-Mitigation: Track user-facing outcomes (time saved, risk avoided, cleanup completed).
-
-## Rollout Narrative
-
-Phase 1: "Safer Changes"
-
-1. Impact Radius
-2. Decision Lineage
-
-Phase 2: "Health and Clarity"
-
-1. Knowledge Health Dashboard
-2. Contradiction Watch
-
-Phase 3: "Strategic Navigation"
-
-1. Path Explorer
-2. Priority Briefs
-
-## One-Line Positioning Options
-
-1. "Local notes, strategic intelligence."
-2. "Know what changed, why it matters, and what it affects."
-3. "From note-taking to decision support."
-
-## Open Questions
-
-1. Which two features best define the paid tier at launch?
-2. Which insight types should be guaranteed deterministic in v1?
-3. Should Priority Briefs be bundled or separate as an add-on?
-4. What is the simplest in-product education flow for first-time premium users?

justfile

@@ -205,6 +205,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"
@@ -83,6 +86,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"},

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/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

@@ -20,6 +20,7 @@ from basic_memory.deps import (
     ProjectConfigV2ExternalDep,
     AppConfigDep,
     EntityRepositoryV2ExternalDep,
+    RelationRepositoryV2ExternalDep,
     ProjectExternalIdPathDep,
     TaskSchedulerDep,
     FileServiceV2ExternalDep,
@@ -31,6 +32,9 @@ from basic_memory.schemas.v2 import (
     EntityResolveRequest,
     EntityResolveResponse,
     EntityResponseV2,
+    GraphEdge,
+    GraphNode,
+    GraphResponse,
     MoveEntityRequestV2,
     MoveDirectoryRequestV2,
     DeleteDirectoryRequestV2,
@@ -56,6 +60,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
 
 

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,39 @@ 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",
+        page=page,
         page_size=page_size,
-        has_more=has_more,
-    )
+        retrieval_mode=query.retrieval_mode.value,
+        has_text_query=bool(query.text and query.text.strip()),
+        has_title_query=bool(query.title),
+        has_permalink_query=bool(query.permalink or query.permalink_match),
+    ):
+        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,
+            page_size=page_size,
+            has_more=has_more,
+        )
 
 
 @router.post("/search/reindex")

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 = 15
+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}"}

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,7 +96,7 @@ 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")
 

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

@@ -128,7 +128,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 +164,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,7 +187,13 @@ 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 = ""
@@ -195,7 +206,7 @@ def list_projects(
                 "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,
             }

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 enum import Enum
 from pathlib import Path
 from typing import Any, Dict, Literal, Optional, List, Tuple
-from enum import Enum
 
 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
 
 
@@ -140,6 +142,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,
@@ -203,6 +223,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(
@@ -351,6 +377,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 +671,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 +710,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 +796,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 +835,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 +975,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,40 +43,37 @@ 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(
+async def _needs_semantic_embedding_backfill(
+    app_config: BasicMemoryConfig,
     session_maker: async_sessionmaker[AsyncSession],
-) -> set[str]:
-    """Load applied Alembic revisions from alembic_version.
+) -> bool:
+    """Check if entities exist but vector embeddings are empty.
 
-    Returns an empty set when the version table does not exist yet
-    (fresh database before first migration).
+    This is the reliable way to detect that embeddings need to be generated,
+    regardless of how migrations were applied (fresh DB, upgrade, reset, etc.).
     """
+    if not app_config.semantic_search_enabled:
+        return False
+
     try:
         async with scoped_session(session_maker) as session:
-            result = await session.execute(text("SELECT version_num FROM alembic_version"))
-            return {str(row[0]) for row in result.fetchall() if row[0]}
+            entity_count = (
+                await session.execute(text("SELECT COUNT(*) FROM entity"))
+            ).scalar() or 0
+            if entity_count == 0:
+                return False
+
+            # Check if vector chunks table exists and is empty
+            embedding_count = (
+                await session.execute(text("SELECT COUNT(*) FROM search_vector_chunks"))
+            ).scalar() or 0
+
+            return embedding_count == 0
     except Exception as exc:
-        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
-    )
+        # Table might not exist yet (pre-migration)
+        logger.debug(f"Could not check embedding status: {exc}")
+        return False
 
 
 async def _run_semantic_embedding_backfill(
@@ -480,26 +477,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 +499,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 +521,14 @@ 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)
+        # Check if backfill is needed — actual backfill runs in background
+        # from the MCP server lifespan to avoid blocking startup.
+        if await _needs_semantic_embedding_backfill(app_config, session_maker):
+            logger.info(
+                "Semantic embeddings missing — backfill will run in background after startup"
+            )
+        else:
+            logger.info("Semantic embeddings: up to date")
     except Exception as e:  # pragma: no cover
         logger.error(f"Error running migrations: {e}")
         raise

src/basic_memory/file_utils.py

@@ -447,6 +447,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/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,26 @@ 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."
+        )
 
 
 @asynccontextmanager

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,6 +64,28 @@ async def _resolve_default_project_from_api() -> Optional[str]:
     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
+
+
+
 async def resolve_project_parameter(
     project: Optional[str] = None,
     allow_discovery: bool = False,
@@ -89,22 +112,28 @@ 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()
+        # 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:
+            default_project = config.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 result.project
+        if default_project is None:
+            default_project = await _resolve_default_project_from_api()
+
+        # 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 +206,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 +282,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}"
+        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}"
+            )
+
+        project = resolved_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,
         )
 
-    project = resolved_project
+        # 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}")
 
-    # 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 +364,77 @@ 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:
+            try:
+                from basic_memory.mcp.tools.utils import call_post
 
-    # 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}'."
+                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}'."
+                    )
 
-            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())
+                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())
 
-            resolved_path = f"{resolved.permalink}/{remainder}" if include_project else remainder
-            return active_project, resolved_path, True
+                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
+        # 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:
@@ -494,9 +548,17 @@ async def get_project_client(
     #   control-plane API with no valid credentials and fail with 401
     # Outcome: use the factory client directly, skip workspace resolution
     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() 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 +566,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 +604,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/server.py

@@ -2,16 +2,70 @@
 Basic Memory FastMCP server.
 """
 
+import asyncio
 import time
 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.config import BasicMemoryConfig
+from basic_memory.db import (
+    scoped_session,
+    _needs_semantic_embedding_backfill,
+    _run_semantic_embedding_backfill,
+)
 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. "
+                "Backfill running in background..."
+            )
+        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}")
+
+
+async def _background_embedding_backfill(
+    config: BasicMemoryConfig,
+    session_maker: async_sessionmaker[AsyncSession],
+) -> None:
+    """Run semantic embedding backfill in the background without blocking startup."""
+    try:
+        if await _needs_semantic_embedding_backfill(config, session_maker):
+            logger.info("Background embedding backfill starting...")
+            await _run_semantic_embedding_backfill(config, session_maker)
+            await _log_embedding_status(session_maker)
+    except Exception as exc:
+        logger.error(f"Background embedding backfill failed: {exc}")
 
 
 @asynccontextmanager
@@ -29,64 +83,96 @@ 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
+        backfill_task: asyncio.Task | None = None  # type: ignore[type-arg]
+        if config.semantic_search_enabled and db._session_maker is not None:
+            await _log_embedding_status(db._session_maker)
+            # Launch backfill in background so MCP server is ready immediately
+            backfill_task = asyncio.create_task(
+                _background_embedding_backfill(config, db._session_maker),
+                name="embedding-backfill",
+            )
+
+        # Create and start sync coordinator (lifecycle centralized in coordinator)
+        sync_coordinator = container.create_sync_coordinator()
+        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")
+            # Cancel embedding backfill if still running
+            if backfill_task is not None and not backfill_task.done():
+                backfill_task.cancel()
+                try:
+                    await backfill_task
+                except asyncio.CancelledError:
+                    logger.info("Background embedding backfill cancelled during shutdown")
+
+            await sync_coordinator.stop()
+
+            # Only shutdown DB if we created it (not if test fixture provided it)
+            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

@@ -8,6 +8,7 @@ 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,212 @@ 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:
+                    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(
-                            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_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,
                     )
-        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_notes(
+                    query=identifier,
+                    search_type="text",
+                    project=active_project.name,
+                    workspace=workspace,
+                    output_format="json",
+                    context=context,
+                )
+
+                # 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,157 @@ 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_metadata_filters=bool(metadata_filters),
+        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/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/repository/search_repository_base.py

@@ -451,21 +451,36 @@ class SearchRepositoryBase(ABC):
         return "\n\n".join(part for part in row_parts if part)
 
     def _build_chunk_records(self, rows) -> list[dict[str, str]]:
-        records: list[dict[str, str]] = []
+        records_by_key: dict[str, dict[str, str]] = {}
+        duplicate_chunk_keys = 0
         for row in rows:
             source_text = self._compose_row_source_text(row)
             chunks = self._split_text_into_chunks(source_text)
             for chunk_index, chunk_text in enumerate(chunks):
                 chunk_key = f"{row.type}:{row.id}:{chunk_index}"
                 source_hash = hashlib.sha256(chunk_text.encode("utf-8")).hexdigest()
-                records.append(
-                    {
-                        "chunk_key": chunk_key,
-                        "chunk_text": chunk_text,
-                        "source_hash": source_hash,
-                    }
-                )
-        return records
+                # Trigger: SQLite FTS5 can accumulate duplicate logical rows for the
+                # same search_index id because it does not enforce relational uniqueness.
+                # Why: duplicate chunk keys would schedule duplicate writes for the same
+                # chunk row and eventually trip UNIQUE(rowid) in search_vector_embeddings.
+                # Outcome: collapse chunk work to one deterministic record per chunk key.
+                if chunk_key in records_by_key:
+                    duplicate_chunk_keys += 1
+                records_by_key[chunk_key] = {
+                    "chunk_key": chunk_key,
+                    "chunk_text": chunk_text,
+                    "source_hash": source_hash,
+                }
+
+        if duplicate_chunk_keys:
+            logger.warning(
+                "Collapsed duplicate vector chunk keys before embedding sync: "
+                "project_id={project_id} duplicate_chunk_keys={duplicate_chunk_keys}",
+                project_id=self.project_id,
+                duplicate_chunk_keys=duplicate_chunk_keys,
+            )
+
+        return list(records_by_key.values())
 
     # --- Text splitting ---
 

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")
 

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

@@ -888,6 +888,14 @@ class EntityService(BaseService[EntityModel]):
                 raise ValueError("section cannot be empty or whitespace only")
             return self.replace_section_content(current_content, section, content)
 
+        elif operation in ("insert_before_section", "insert_after_section"):
+            if not section:
+                raise ValueError("section is required for insert section operations")
+            if not section.strip():
+                raise ValueError("section cannot be empty or whitespace only")
+            position = "before" if operation == "insert_before_section" else "after"
+            return self.insert_relative_to_section(current_content, section, content, position)
+
         else:
             raise ValueError(f"Unsupported operation: {operation}")
 
@@ -979,6 +987,73 @@ class EntityService(BaseService[EntityModel]):
 
         return "\n".join(result_lines)
 
+    def insert_relative_to_section(
+        self,
+        current_content: str,
+        section_header: str,
+        new_content: str,
+        position: str,
+    ) -> str:
+        """Insert content before or after a section heading without consuming it.
+
+        Unlike replace_section_content, this preserves the section heading and its
+        existing content. The new content is inserted immediately before or after
+        the heading line.
+
+        Args:
+            current_content: The current markdown content
+            section_header: The section header to anchor on (e.g., "## Section Name")
+            new_content: The content to insert
+            position: "before" to insert above the heading, "after" to insert below it
+
+        Returns:
+            The updated content with new_content inserted relative to the heading
+
+        Raises:
+            ValueError: If the section header is not found or appears more than once
+        """
+        # Normalize the section header (ensure it starts with #)
+        if not section_header.startswith("#"):
+            section_header = "## " + section_header
+
+        lines = current_content.split("\n")
+        matching_indices = [
+            i for i, line in enumerate(lines) if line.strip() == section_header.strip()
+        ]
+
+        if len(matching_indices) == 0:
+            raise ValueError(
+                f"Section '{section_header}' not found in document. "
+                f"Use replace_section to create a new section."
+            )
+        if len(matching_indices) > 1:
+            raise ValueError(
+                f"Multiple sections found with header '{section_header}'. "
+                f"Section insertion requires unique headers."
+            )
+
+        idx = matching_indices[0]
+
+        if position == "before":
+            # Insert new content before the section heading
+            before = lines[:idx]
+            after = lines[idx:]
+            # Ensure blank line separation
+            insert_lines = new_content.rstrip("\n").split("\n")
+            if before and before[-1].strip() != "":
+                insert_lines = [""] + insert_lines
+            return "\n".join(before + insert_lines + [""] + after)
+        else:
+            # Insert new content after the section heading line
+            before = lines[: idx + 1]
+            after = lines[idx + 1 :]
+            insert_lines = new_content.rstrip("\n").split("\n")
+            # Ensure blank line separation so inserted text doesn't merge
+            # with existing section content into a single paragraph
+            if after and after[0].strip() != "":
+                insert_lines = insert_lines + [""]
+            return "\n".join(before + insert_lines + after)
+
     def _prepend_after_frontmatter(self, current_content: str, content: str) -> str:
         """Prepend content after frontmatter, preserving frontmatter structure."""
 

src/basic_memory/services/project_service.py

@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING, Dict, Optional, Sequence
 
 from loguru import logger
 from sqlalchemy import text
+from sqlalchemy.exc import OperationalError as SAOperationalError
 
 from basic_memory.models import Project
 from basic_memory.repository.project_repository import ProjectRepository
@@ -996,64 +997,101 @@ class ProjectService:
             )
 
         # --- Count queries (tables exist) ---
+        # Filter by entity existence to exclude stale rows from deleted entities
+        # that remain in derived search tables (search_index, search_vector_chunks)
+        entity_exists = "AND entity_id IN (SELECT id FROM entity WHERE project_id = :project_id)"
+        # Same filter for aliased chunks table (used in JOIN queries below)
+        chunk_entity_exists = (
+            "AND c.entity_id IN (SELECT id FROM entity WHERE project_id = :project_id)"
+        )
+
         si_result = await self.repository.execute_query(
             text(
-                "SELECT COUNT(DISTINCT entity_id) FROM search_index WHERE project_id = :project_id"
+                "SELECT COUNT(DISTINCT entity_id) FROM search_index "
+                f"WHERE project_id = :project_id {entity_exists}"
             ),
             {"project_id": project_id},
         )
         total_indexed_entities = si_result.scalar() or 0
 
-        chunks_result = await self.repository.execute_query(
-            text("SELECT COUNT(*) FROM search_vector_chunks WHERE project_id = :project_id"),
-            {"project_id": project_id},
-        )
-        total_chunks = chunks_result.scalar() or 0
-
-        entities_with_chunks_result = await self.repository.execute_query(
-            text(
-                "SELECT COUNT(DISTINCT entity_id) FROM search_vector_chunks "
-                "WHERE project_id = :project_id"
-            ),
-            {"project_id": project_id},
-        )
-        total_entities_with_chunks = entities_with_chunks_result.scalar() or 0
-
-        # Embeddings count — join pattern differs between SQLite and Postgres
-        if is_postgres:
-            embeddings_sql = text(
-                "SELECT COUNT(*) FROM search_vector_chunks c "
-                "JOIN search_vector_embeddings e ON e.chunk_id = c.id "
-                "WHERE c.project_id = :project_id"
-            )
-        else:
-            embeddings_sql = text(
-                "SELECT COUNT(*) FROM search_vector_chunks c "
-                "JOIN search_vector_embeddings e ON e.rowid = c.id "
-                "WHERE c.project_id = :project_id"
+        try:
+            chunks_result = await self.repository.execute_query(
+                text(
+                    "SELECT COUNT(*) FROM search_vector_chunks "
+                    f"WHERE project_id = :project_id {entity_exists}"
+                ),
+                {"project_id": project_id},
             )
+            total_chunks = chunks_result.scalar() or 0
 
-        embeddings_result = await self.repository.execute_query(
-            embeddings_sql, {"project_id": project_id}
-        )
-        total_embeddings = embeddings_result.scalar() or 0
-
-        # Orphaned chunks (chunks without embeddings — indicates interrupted indexing)
-        if is_postgres:
-            orphan_sql = text(
-                "SELECT COUNT(*) FROM search_vector_chunks c "
-                "LEFT JOIN search_vector_embeddings e ON e.chunk_id = c.id "
-                "WHERE c.project_id = :project_id AND e.chunk_id IS NULL"
-            )
-        else:
-            orphan_sql = text(
-                "SELECT COUNT(*) FROM search_vector_chunks c "
-                "LEFT JOIN search_vector_embeddings e ON e.rowid = c.id "
-                "WHERE c.project_id = :project_id AND e.rowid IS NULL"
+            entities_with_chunks_result = await self.repository.execute_query(
+                text(
+                    "SELECT COUNT(DISTINCT entity_id) FROM search_vector_chunks "
+                    f"WHERE project_id = :project_id {entity_exists}"
+                ),
+                {"project_id": project_id},
             )
+            total_entities_with_chunks = entities_with_chunks_result.scalar() or 0
 
-        orphan_result = await self.repository.execute_query(orphan_sql, {"project_id": project_id})
-        orphaned_chunks = orphan_result.scalar() or 0
+            # Embeddings count — join pattern differs between SQLite and Postgres
+            if is_postgres:
+                embeddings_sql = text(
+                    "SELECT COUNT(*) FROM search_vector_chunks c "
+                    "JOIN search_vector_embeddings e ON e.chunk_id = c.id "
+                    f"WHERE c.project_id = :project_id {chunk_entity_exists}"
+                )
+            else:
+                embeddings_sql = text(
+                    "SELECT COUNT(*) FROM search_vector_chunks c "
+                    "JOIN search_vector_embeddings e ON e.rowid = c.id "
+                    f"WHERE c.project_id = :project_id {chunk_entity_exists}"
+                )
+
+            embeddings_result = await self.repository.execute_query(
+                embeddings_sql, {"project_id": project_id}
+            )
+            total_embeddings = embeddings_result.scalar() or 0
+
+            # Orphaned chunks (chunks without embeddings — indicates interrupted indexing)
+            if is_postgres:
+                orphan_sql = text(
+                    "SELECT COUNT(*) FROM search_vector_chunks c "
+                    "LEFT JOIN search_vector_embeddings e ON e.chunk_id = c.id "
+                    f"WHERE c.project_id = :project_id AND e.chunk_id IS NULL {chunk_entity_exists}"
+                )
+            else:
+                orphan_sql = text(
+                    "SELECT COUNT(*) FROM search_vector_chunks c "
+                    "LEFT JOIN search_vector_embeddings e ON e.rowid = c.id "
+                    f"WHERE c.project_id = :project_id AND e.rowid IS NULL {chunk_entity_exists}"
+                )
+
+            orphan_result = await self.repository.execute_query(
+                orphan_sql, {"project_id": project_id}
+            )
+            orphaned_chunks = orphan_result.scalar() or 0
+        except SAOperationalError as exc:
+            # Trigger: sqlite_master can list vec0 virtual tables even when sqlite-vec
+            # is not loaded in the current Python runtime.
+            # Why: project info should degrade gracefully instead of crashing on stats queries.
+            # Outcome: report vector tables as unavailable and point the user to install the
+            # missing dependency before rebuilding embeddings.
+            if is_postgres or "no such module: vec0" not in str(exc).lower():
+                raise
+
+            return EmbeddingStatus(
+                semantic_search_enabled=True,
+                embedding_provider=provider,
+                embedding_model=model,
+                embedding_dimensions=dimensions,
+                total_indexed_entities=total_indexed_entities,
+                vector_tables_exist=False,
+                reindex_recommended=True,
+                reindex_reason=(
+                    "SQLite vector tables exist but sqlite-vec is unavailable in this Python "
+                    "environment — install/update basic-memory, then run: bm reindex --embeddings"
+                ),
+            )
 
         # --- Reindex recommendation logic (priority order) ---
         reindex_recommended = False

src/basic_memory/services/search_service.py

@@ -5,12 +5,12 @@ import re
 from datetime import datetime
 from typing import List, Optional, Set, Dict, Any
 
-
 from dateparser import parse
 from fastapi import BackgroundTasks
 from loguru import logger
 from sqlalchemy import text
 
+from basic_memory import telemetry
 from basic_memory.models import Entity
 from basic_memory.repository import EntityRepository
 from basic_memory.repository.search_repository import (
@@ -152,8 +152,6 @@ class SearchService:
             logger.debug("no criteria passed to query")
             return []
 
-        logger.trace(f"Searching with query: {query}")
-
         after_date = (
             (
                 query.after_date
@@ -176,21 +174,32 @@ class SearchService:
         retrieval_mode = query.retrieval_mode or SearchRetrievalMode.FTS
         strict_search_text = query.text
 
-        # First pass: preserve existing strict search behavior.
-        results = await self.repository.search(
-            search_text=strict_search_text,
-            permalink=query.permalink,
-            permalink_match=query.permalink_match,
-            title=query.title,
-            note_types=query.note_types,
-            search_item_types=query.entity_types,
-            after_date=after_date,
-            metadata_filters=metadata_filters,
-            retrieval_mode=retrieval_mode,
-            min_similarity=query.min_similarity,
+        with telemetry.scope(
+            "search.execute",
+            retrieval_mode=retrieval_mode.value,
+            has_text_query=bool(strict_search_text),
+            has_title_query=bool(query.title),
+            has_permalink_query=bool(query.permalink or query.permalink_match),
+            has_metadata_filters=bool(metadata_filters),
             limit=limit,
             offset=offset,
-        )
+        ):
+            logger.trace(f"Searching with query: {query}")
+            # First pass: preserve existing strict search behavior.
+            results = await self.repository.search(
+                search_text=strict_search_text,
+                permalink=query.permalink,
+                permalink_match=query.permalink_match,
+                title=query.title,
+                note_types=query.note_types,
+                search_item_types=query.entity_types,
+                after_date=after_date,
+                metadata_filters=metadata_filters,
+                retrieval_mode=retrieval_mode,
+                min_similarity=query.min_similarity,
+                limit=limit,
+                offset=offset,
+            )
 
         # Trigger: strict FTS with plain multi-term text returned no results.
         # Why: natural-language queries often include stopwords that over-constrain implicit AND.
@@ -209,20 +218,27 @@ class SearchService:
             "Strict FTS returned 0 results; retrying relaxed FTS query "
             f"strict='{strict_search_text}' relaxed='{relaxed_search_text}'"
         )
-        return await self.repository.search(
-            search_text=relaxed_search_text,
-            permalink=query.permalink,
-            permalink_match=query.permalink_match,
-            title=query.title,
-            note_types=query.note_types,
-            search_item_types=query.entity_types,
-            after_date=after_date,
-            metadata_filters=metadata_filters,
-            retrieval_mode=retrieval_mode,
-            min_similarity=query.min_similarity,
+        with telemetry.scope(
+            "search.relaxed_fts_retry",
+            retrieval_mode=retrieval_mode.value,
+            token_count=len(self._tokenize_fts_text(strict_search_text)),
             limit=limit,
             offset=offset,
-        )
+        ):
+            return await self.repository.search(
+                search_text=relaxed_search_text,
+                permalink=query.permalink,
+                permalink_match=query.permalink_match,
+                title=query.title,
+                note_types=query.note_types,
+                search_item_types=query.entity_types,
+                after_date=after_date,
+                metadata_filters=metadata_filters,
+                retrieval_mode=retrieval_mode,
+                min_similarity=query.min_similarity,
+                limit=limit,
+                offset=offset,
+            )
 
     @staticmethod
     def _tokenize_fts_text(search_text: str) -> list[str]:
@@ -403,6 +419,11 @@ class SearchService:
         """
         entities = await self.entity_repository.find_all()
         entity_ids = [entity.id for entity in entities]
+
+        # Clean up stale rows in search_index and search_vector_chunks
+        # that reference entity_ids no longer in the entity table
+        await self._purge_stale_search_rows()
+
         batch_result = await self.repository.sync_entity_vectors_batch(
             entity_ids,
             progress_callback=progress_callback,
@@ -419,6 +440,52 @@ class SearchService:
 
         return stats
 
+    async def _purge_stale_search_rows(self) -> None:
+        """Remove rows from search_index and search_vector_chunks for deleted entities.
+
+        Trigger: entities are deleted but their derived search rows remain
+        Why: stale rows inflate embedding coverage stats in project info
+        Outcome: search tables only contain rows for entities that still exist
+        """
+        from basic_memory.repository.sqlite_search_repository import SQLiteSearchRepository
+        from sqlalchemy import text
+
+        project_id = self.repository.project_id
+        stale_entity_filter = (
+            "entity_id NOT IN (SELECT id FROM entity WHERE project_id = :project_id)"
+        )
+        params = {"project_id": project_id}
+
+        # Delete stale search_index rows
+        await self.repository.execute_query(
+            text(
+                f"DELETE FROM search_index WHERE project_id = :project_id AND {stale_entity_filter}"
+            ),
+            params,
+        )
+
+        # SQLite vec has no CASCADE — must delete embeddings before chunks
+        if isinstance(self.repository, SQLiteSearchRepository):
+            await self.repository.execute_query(
+                text(
+                    "DELETE FROM search_vector_embeddings WHERE rowid IN ("
+                    "SELECT id FROM search_vector_chunks "
+                    f"WHERE project_id = :project_id AND {stale_entity_filter})"
+                ),
+                params,
+            )
+
+        # Postgres CASCADE handles embedding deletion automatically
+        await self.repository.execute_query(
+            text(
+                f"DELETE FROM search_vector_chunks "
+                f"WHERE project_id = :project_id AND {stale_entity_filter}"
+            ),
+            params,
+        )
+
+        logger.info("Purged stale search rows for deleted entities", project_id=project_id)
+
     async def index_entity_file(
         self,
         entity: Entity,

src/basic_memory/sync/sync_service.py

@@ -15,6 +15,7 @@ import aiofiles.os
 from loguru import logger
 from sqlalchemy.exc import IntegrityError
 
+from basic_memory import telemetry
 from basic_memory import db
 from basic_memory.config import BasicMemoryConfig, ConfigManager
 from basic_memory.file_utils import has_frontmatter
@@ -36,6 +37,7 @@ from basic_memory.services.search_service import SearchService
 
 # Circuit breaker configuration
 MAX_CONSECUTIVE_FAILURES = 3
+SLOW_FILE_SYNC_WARNING_MS = 500
 
 
 @dataclass
@@ -265,112 +267,161 @@ class SyncService:
 
         start_time = time.time()
         sync_start_timestamp = time.time()  # Capture at start for watermark
-        logger.info(f"Sync operation started for directory: {directory} (force_full={force_full})")
-
-        # initial paths from db to sync
-        # path -> checksum
-        report = await self.scan(directory, force_full=force_full)
-
-        # order of sync matters to resolve relations effectively
-        logger.info(
-            f"Sync changes detected: new_files={len(report.new)}, modified_files={len(report.modified)}, "
-            + f"deleted_files={len(report.deleted)}, moved_files={len(report.moves)}"
-        )
-
-        # sync moves first
-        for old_path, new_path in report.moves.items():
-            # in the case where a file has been deleted and replaced by another file
-            # it will show up in the move and modified lists, so handle it in modified
-            if new_path in report.modified:
-                report.modified.remove(new_path)
-                logger.debug(
-                    f"File marked as moved and modified: old_path={old_path}, new_path={new_path}"
-                )
-            else:
-                await self.handle_move(old_path, new_path)
-
-        # deleted next
-        for path in report.deleted:
-            await self.handle_delete(path)
-
-        # then new and modified
-        for path in report.new:
-            entity, _ = await self.sync_file(path, new=True)
-
-            # Track if file was skipped
-            if entity is None and await self._should_skip_file(path):
-                failure_info = self._file_failures[path]
-                report.skipped_files.append(
-                    SkippedFile(
-                        path=path,
-                        reason=failure_info.last_error,
-                        failure_count=failure_info.count,
-                        first_failed=failure_info.first_failure,
-                    )
-                )
-
-        for path in report.modified:
-            entity, _ = await self.sync_file(path, new=False)
-
-            # Track if file was skipped
-            if entity is None and await self._should_skip_file(path):
-                failure_info = self._file_failures[path]
-                report.skipped_files.append(
-                    SkippedFile(
-                        path=path,
-                        reason=failure_info.last_error,
-                        failure_count=failure_info.count,
-                        first_failed=failure_info.first_failure,
-                    )
-                )
-
-        # Only resolve relations if there were actual changes
-        # If no files changed, no new unresolved relations could have been created
-        if report.total > 0:
-            await self.resolve_relations()
-        else:
-            logger.info("Skipping relation resolution - no file changes detected")
-
-        # Update scan watermark after successful sync
-        # Use the timestamp from sync start (not end) to ensure we catch files
-        # created during the sync on the next iteration
-        current_file_count = await self._quick_count_files(directory)
-        if self.entity_repository.project_id is not None:
-            project = await self.project_repository.find_by_id(self.entity_repository.project_id)
-            if project:
-                await self.project_repository.update(
-                    project.id,
-                    {
-                        "last_scan_timestamp": sync_start_timestamp,
-                        "last_file_count": current_file_count,
-                    },
-                )
-                logger.debug(
-                    f"Updated scan watermark: timestamp={sync_start_timestamp}, "
-                    f"file_count={current_file_count}"
-                )
-
-        duration_ms = int((time.time() - start_time) * 1000)
-
-        # Log summary with skipped files if any
-        if report.skipped_files:
-            logger.warning(
-                f"Sync completed with {len(report.skipped_files)} skipped files: "
-                f"directory={directory}, total_changes={report.total}, "
-                f"skipped={len(report.skipped_files)}, duration_ms={duration_ms}"
-            )
-            for skipped in report.skipped_files:
-                logger.warning(
-                    f"Skipped file: path={skipped.path}, "
-                    f"failures={skipped.failure_count}, reason={skipped.reason}"
-                )
-        else:
+        with telemetry.operation(
+            "sync.project.run",
+            project_name=project_name,
+            force_full=force_full,
+        ):
             logger.info(
-                f"Sync operation completed: directory={directory}, "
-                f"total_changes={report.total}, duration_ms={duration_ms}"
+                f"Sync operation started for directory: {directory} (force_full={force_full})"
             )
 
-        return report
+            # initial paths from db to sync
+            # path -> checksum
+            with telemetry.scope("sync.project.scan", force_full=force_full):
+                report = await self.scan(directory, force_full=force_full)
+
+            # order of sync matters to resolve relations effectively
+            logger.info(
+                f"Sync changes detected: new_files={len(report.new)}, modified_files={len(report.modified)}, "
+                + f"deleted_files={len(report.deleted)}, moved_files={len(report.moves)}"
+            )
+
+            with telemetry.scope(
+                "sync.project.apply_changes",
+                new_count=len(report.new),
+                modified_count=len(report.modified),
+                deleted_count=len(report.deleted),
+                move_count=len(report.moves),
+            ):
+                # sync moves first
+                for old_path, new_path in report.moves.items():
+                    # in the case where a file has been deleted and replaced by another file
+                    # it will show up in the move and modified lists, so handle it in modified
+                    if new_path in report.modified:
+                        report.modified.remove(new_path)
+                        logger.debug(
+                            f"File marked as moved and modified: old_path={old_path}, new_path={new_path}"
+                        )
+                    else:
+                        await self.handle_move(old_path, new_path)
+
+                # deleted next
+                for path in report.deleted:
+                    await self.handle_delete(path)
+
+                # then new and modified — collect entity IDs for batch vector embedding
+                synced_entity_ids: list[int] = []
+
+                for path in report.new:
+                    entity, _ = await self.sync_file(path, new=True)
+
+                    if entity is not None:
+                        synced_entity_ids.append(entity.id)
+                    # Track if file was skipped
+                    elif await self._should_skip_file(path):
+                        failure_info = self._file_failures[path]
+                        report.skipped_files.append(
+                            SkippedFile(
+                                path=path,
+                                reason=failure_info.last_error,
+                                failure_count=failure_info.count,
+                                first_failed=failure_info.first_failure,
+                            )
+                        )
+
+                for path in report.modified:
+                    entity, _ = await self.sync_file(path, new=False)
+
+                    if entity is not None:
+                        synced_entity_ids.append(entity.id)
+                    # Track if file was skipped
+                    elif await self._should_skip_file(path):
+                        failure_info = self._file_failures[path]
+                        report.skipped_files.append(
+                            SkippedFile(
+                                path=path,
+                                reason=failure_info.last_error,
+                                failure_count=failure_info.count,
+                                first_failed=failure_info.first_failure,
+                            )
+                        )
+
+            # Only resolve relations if there were actual changes
+            # If no files changed, no new unresolved relations could have been created
+            if report.total > 0:
+                with telemetry.scope("sync.project.resolve_relations", relation_scope="all_pending"):
+                    await self.resolve_relations()
+            else:
+                logger.info("Skipping relation resolution - no file changes detected")
+
+            # Batch-generate vector embeddings for all synced entities
+            if synced_entity_ids and self.app_config.semantic_search_enabled:
+                try:
+                    with telemetry.scope(
+                        "sync.project.sync_embeddings",
+                        entity_count=len(synced_entity_ids),
+                    ):
+                        logger.info(
+                            f"Generating semantic embeddings for {len(synced_entity_ids)} entities..."
+                        )
+                        batch_result = await self.search_service.sync_entity_vectors_batch(
+                            synced_entity_ids
+                        )
+                        logger.info(
+                            f"Semantic embeddings complete: "
+                            f"synced={batch_result.entities_synced}, "
+                            f"failed={batch_result.entities_failed}"
+                        )
+                except SemanticDependenciesMissingError:
+                    logger.warning(
+                        "Semantic search dependencies missing — vector embeddings skipped. "
+                        "Run 'bm reindex --embeddings' after resolving the dependency issue."
+                    )
+
+            # Update scan watermark after successful sync
+            # Use the timestamp from sync start (not end) to ensure we catch files
+            # created during the sync on the next iteration
+            with telemetry.scope("sync.project.update_watermark"):
+                current_file_count = await self._quick_count_files(directory)
+                if self.entity_repository.project_id is not None:
+                    project = await self.project_repository.find_by_id(
+                        self.entity_repository.project_id
+                    )
+                    if project:
+                        await self.project_repository.update(
+                            project.id,
+                            {
+                                "last_scan_timestamp": sync_start_timestamp,
+                                "last_file_count": current_file_count,
+                            },
+                        )
+                        logger.debug(
+                            f"Updated scan watermark: timestamp={sync_start_timestamp}, "
+                            f"file_count={current_file_count}"
+                        )
+
+            duration_ms = int((time.time() - start_time) * 1000)
+
+            # Log summary with skipped files if any
+            if report.skipped_files:
+                logger.warning(
+                    f"Sync completed with {len(report.skipped_files)} skipped files: "
+                    f"directory={directory}, total_changes={report.total}, "
+                    f"skipped={len(report.skipped_files)}, duration_ms={duration_ms}"
+                )
+                for skipped in report.skipped_files:
+                    logger.warning(
+                        f"Skipped file: path={skipped.path}, "
+                        f"failures={skipped.failure_count}, reason={skipped.reason}"
+                    )
+            else:
+                logger.info(
+                    f"Sync operation completed: directory={directory}, "
+                    f"total_changes={report.total}, duration_ms={duration_ms}"
+                )
+
+            return report
 
     async def scan(self, directory, force_full: bool = False):
         """Smart scan using watermark and file count for large project optimization.
@@ -407,171 +458,180 @@ class SyncService:
         if project is None:
             raise ValueError(f"Project not found: {self.entity_repository.project_id}")
 
-        # Step 1: Quick file count
-        logger.debug("Counting files in directory")
-        current_count = await self._quick_count_files(directory)
-        logger.debug(f"Found {current_count} files in directory")
+        with telemetry.scope("sync.project.select_scan_strategy", force_full=force_full):
+            # Step 1: Quick file count
+            logger.debug("Counting files in directory")
+            current_count = await self._quick_count_files(directory)
+            logger.debug(f"Found {current_count} files in directory")
 
-        # Step 2: Determine scan strategy based on watermark and file count
-        if force_full:
-            # User explicitly requested full scan → bypass watermark optimization
-            scan_type = "full_forced"
-            logger.info("Force full scan requested, bypassing watermark optimization")
-            file_paths_to_scan = await self._scan_directory_full(directory)
+            # Step 2: Determine scan strategy based on watermark and file count
+            if force_full:
+                # User explicitly requested full scan → bypass watermark optimization
+                scan_type = "full_forced"
+                logger.info("Force full scan requested, bypassing watermark optimization")
+                scan_coro = self._scan_directory_full(directory)
 
-        elif project.last_file_count is None:
-            # First sync ever → full scan
-            scan_type = "full_initial"
-            logger.info("First sync for this project, performing full scan")
-            file_paths_to_scan = await self._scan_directory_full(directory)
+            elif project.last_file_count is None:
+                # First sync ever → full scan
+                scan_type = "full_initial"
+                logger.info("First sync for this project, performing full scan")
+                scan_coro = self._scan_directory_full(directory)
 
-        elif current_count < project.last_file_count:
-            # Files deleted → need full scan to detect which ones
-            scan_type = "full_deletions"
-            logger.info(
-                f"File count decreased ({project.last_file_count} → {current_count}), "
-                f"running full scan to detect deletions"
-            )
-            file_paths_to_scan = await self._scan_directory_full(directory)
+            elif current_count < project.last_file_count:
+                # Files deleted → need full scan to detect which ones
+                scan_type = "full_deletions"
+                logger.info(
+                    f"File count decreased ({project.last_file_count} → {current_count}), "
+                    f"running full scan to detect deletions"
+                )
+                scan_coro = self._scan_directory_full(directory)
 
-        elif project.last_scan_timestamp is not None:
-            # Incremental scan: only files modified since last scan
-            scan_type = "incremental"
-            logger.debug(
-                f"Running incremental scan for files modified since {project.last_scan_timestamp}"
-            )
-            file_paths_to_scan = await self._scan_directory_modified_since(
-                directory, project.last_scan_timestamp
-            )
-            logger.debug(
-                f"Incremental scan found {len(file_paths_to_scan)} potentially changed files"
-            )
+            elif project.last_scan_timestamp is not None:
+                # Incremental scan: only files modified since last scan
+                scan_type = "incremental"
+                logger.debug(
+                    f"Running incremental scan for files modified since {project.last_scan_timestamp}"
+                )
+                scan_coro = self._scan_directory_modified_since(
+                    directory, project.last_scan_timestamp
+                )
 
-        else:
-            # Fallback to full scan (no watermark available)
-            scan_type = "full_fallback"
-            logger.warning("No scan watermark available, falling back to full scan")
-            file_paths_to_scan = await self._scan_directory_full(directory)
-
-        # Step 3: Process each file with mtime-based comparison
-        scanned_paths: Set[str] = set()
-        changed_checksums: Dict[str, str] = {}
-
-        logger.debug(f"Processing {len(file_paths_to_scan)} files with mtime-based comparison")
-
-        for rel_path in file_paths_to_scan:
-            scanned_paths.add(rel_path)
-
-            # Get file stats
-            abs_path = directory / rel_path
-            if not abs_path.exists():
-                # File was deleted between scan and now (race condition)
-                continue
-
-            stat_info = abs_path.stat()
-
-            # Indexed lookup - single file query (not full table scan)
-            db_entity = await self.entity_repository.get_by_file_path(rel_path)
-
-            if db_entity is None:
-                # New file - need checksum for move detection
-                checksum = await self.file_service.compute_checksum(rel_path)
-                report.new.add(rel_path)
-                changed_checksums[rel_path] = checksum
-                logger.trace(f"New file detected: {rel_path}")
-                continue
-
-            # File exists in DB - check if mtime/size changed
-            db_mtime = db_entity.mtime
-            db_size = db_entity.size
-            fs_mtime = stat_info.st_mtime
-            fs_size = stat_info.st_size
-
-            # Compare mtime and size (like rsync/rclone)
-            # Allow small epsilon for float comparison (0.01s = 10ms)
-            mtime_changed = db_mtime is None or abs(fs_mtime - db_mtime) > 0.01
-            size_changed = db_size is None or fs_size != db_size
-
-            if mtime_changed or size_changed:
-                # File modified - compute checksum
-                checksum = await self.file_service.compute_checksum(rel_path)
-                db_checksum = db_entity.checksum
-
-                # Only mark as modified if checksum actually differs
-                # (handles cases where mtime changed but content didn't, e.g., git operations)
-                if checksum != db_checksum:
-                    report.modified.add(rel_path)
-                    changed_checksums[rel_path] = checksum
-                    logger.trace(
-                        f"Modified file detected: {rel_path}, "
-                        f"mtime_changed={mtime_changed}, size_changed={size_changed}"
-                    )
             else:
-                # File unchanged - no checksum needed
-                logger.trace(f"File unchanged (mtime/size match): {rel_path}")
+                # Fallback to full scan (no watermark available)
+                scan_type = "full_fallback"
+                logger.warning("No scan watermark available, falling back to full scan")
+                scan_coro = self._scan_directory_full(directory)
 
-        # Step 4: Detect moves (for both full and incremental scans)
-        # Check if any "new" files are actually moves by matching checksums
-        for new_path in list(report.new):  # Use list() to allow modification during iteration
-            new_checksum = changed_checksums.get(new_path)
-            if not new_checksum:
-                continue
+        with telemetry.scope("sync.project.filesystem_scan", scan_type=scan_type):
+            file_paths_to_scan = await scan_coro
+            if scan_type == "incremental":
+                logger.debug(
+                    f"Incremental scan found {len(file_paths_to_scan)} potentially changed files"
+                )
 
-            # Look for existing entity with same checksum but different path
-            # This could be a move or a copy
-            existing_entities = await self.entity_repository.find_by_checksum(new_checksum)
+            # Step 3: Process each file with mtime-based comparison
+            scanned_paths: Set[str] = set()
+            changed_checksums: Dict[str, str] = {}
 
-            for candidate in existing_entities:
-                if candidate.file_path == new_path:
-                    # Same path, skip (shouldn't happen for "new" files but be safe)
+            logger.debug(f"Processing {len(file_paths_to_scan)} files with mtime-based comparison")
+
+            for rel_path in file_paths_to_scan:
+                scanned_paths.add(rel_path)
+
+                # Get file stats
+                abs_path = directory / rel_path
+                if not abs_path.exists():
+                    # File was deleted between scan and now (race condition)
                     continue
 
-                # Check if the old path still exists on disk
-                old_path_abs = directory / candidate.file_path
-                if old_path_abs.exists():
-                    # Original still exists → this is a copy, not a move
-                    logger.trace(
-                        f"File copy detected (not move): {candidate.file_path} copied to {new_path}"
-                    )
+                stat_info = abs_path.stat()
+
+                # Indexed lookup - single file query (not full table scan)
+                db_entity = await self.entity_repository.get_by_file_path(rel_path)
+
+                if db_entity is None:
+                    # New file - need checksum for move detection
+                    checksum = await self.file_service.compute_checksum(rel_path)
+                    report.new.add(rel_path)
+                    changed_checksums[rel_path] = checksum
+                    logger.trace(f"New file detected: {rel_path}")
                     continue
 
-                # Original doesn't exist → this is a move!
-                report.moves[candidate.file_path] = new_path
-                report.new.remove(new_path)
-                logger.trace(f"Move detected: {candidate.file_path} -> {new_path}")
-                break  # Only match first candidate
+                # File exists in DB - check if mtime/size changed
+                db_mtime = db_entity.mtime
+                db_size = db_entity.size
+                fs_mtime = stat_info.st_mtime
+                fs_size = stat_info.st_size
 
-        # Step 5: Detect deletions (only for full scans)
-        # Incremental scans can't reliably detect deletions since they only see modified files
-        if scan_type in ("full_initial", "full_deletions", "full_fallback", "full_forced"):
-            # Use optimized query for just file paths (not full entities)
-            db_file_paths = await self.entity_repository.get_all_file_paths()
-            logger.debug(f"Found {len(db_file_paths)} db paths for deletion detection")
+                # Compare mtime and size (like rsync/rclone)
+                # Allow small epsilon for float comparison (0.01s = 10ms)
+                mtime_changed = db_mtime is None or abs(fs_mtime - db_mtime) > 0.01
+                size_changed = db_size is None or fs_size != db_size
 
-            for db_path in db_file_paths:
-                if db_path not in scanned_paths:
-                    # File in DB but not on filesystem
-                    # Check if it was already detected as a move
-                    if db_path in report.moves:
-                        # Already handled as a move, skip
+                if mtime_changed or size_changed:
+                    # File modified - compute checksum
+                    checksum = await self.file_service.compute_checksum(rel_path)
+                    db_checksum = db_entity.checksum
+
+                    # Only mark as modified if checksum actually differs
+                    # (handles cases where mtime changed but content didn't, e.g., git operations)
+                    if checksum != db_checksum:
+                        report.modified.add(rel_path)
+                        changed_checksums[rel_path] = checksum
+                        logger.trace(
+                            f"Modified file detected: {rel_path}, "
+                            f"mtime_changed={mtime_changed}, size_changed={size_changed}"
+                        )
+                else:
+                    # File unchanged - no checksum needed
+                    logger.trace(f"File unchanged (mtime/size match): {rel_path}")
+
+            # Step 4: Detect moves (for both full and incremental scans)
+            # Check if any "new" files are actually moves by matching checksums
+            with telemetry.scope("sync.project.detect_moves", new_count=len(report.new)):
+                for new_path in list(
+                    report.new
+                ):  # Use list() to allow modification during iteration
+                    new_checksum = changed_checksums.get(new_path)
+                    if not new_checksum:
                         continue
 
-                    # File was deleted
-                    report.deleted.add(db_path)
-                    logger.trace(f"Deleted file detected: {db_path}")
+                    # Look for existing entity with same checksum but different path
+                    # This could be a move or a copy
+                    existing_entities = await self.entity_repository.find_by_checksum(new_checksum)
 
-        # Store checksums for files that need syncing
-        report.checksums = changed_checksums
+                    for candidate in existing_entities:
+                        if candidate.file_path == new_path:
+                            # Same path, skip (shouldn't happen for "new" files but be safe)
+                            continue
 
-        scan_duration_ms = int((time.time() - scan_start_time) * 1000)
+                        # Check if the old path still exists on disk
+                        old_path_abs = directory / candidate.file_path
+                        if old_path_abs.exists():
+                            # Original still exists → this is a copy, not a move
+                            logger.trace(
+                                f"File copy detected (not move): {candidate.file_path} copied to {new_path}"
+                            )
+                            continue
 
-        logger.info(
-            f"Completed {scan_type} scan for directory {directory} in {scan_duration_ms}ms, "
-            f"found {report.total} changes (new={len(report.new)}, "
-            f"modified={len(report.modified)}, deleted={len(report.deleted)}, "
-            f"moves={len(report.moves)})"
-        )
-        return report
+                        # Original doesn't exist → this is a move!
+                        report.moves[candidate.file_path] = new_path
+                        report.new.remove(new_path)
+                        logger.trace(f"Move detected: {candidate.file_path} -> {new_path}")
+                        break  # Only match first candidate
+
+            # Step 5: Detect deletions (only for full scans)
+            # Incremental scans can't reliably detect deletions since they only see modified files
+            if scan_type in ("full_initial", "full_deletions", "full_fallback", "full_forced"):
+                with telemetry.scope("sync.project.detect_deletions", scan_type=scan_type):
+                    # Use optimized query for just file paths (not full entities)
+                    db_file_paths = await self.entity_repository.get_all_file_paths()
+                    logger.debug(f"Found {len(db_file_paths)} db paths for deletion detection")
+
+                    for db_path in db_file_paths:
+                        if db_path not in scanned_paths:
+                            # File in DB but not on filesystem
+                            # Check if it was already detected as a move
+                            if db_path in report.moves:
+                                # Already handled as a move, skip
+                                continue
+
+                            # File was deleted
+                            report.deleted.add(db_path)
+                            logger.trace(f"Deleted file detected: {db_path}")
+
+            # Store checksums for files that need syncing
+            report.checksums = changed_checksums
+
+            scan_duration_ms = int((time.time() - scan_start_time) * 1000)
+
+            logger.info(
+                f"Completed {scan_type} scan for directory {directory} in {scan_duration_ms}ms, "
+                f"found {report.total} changes (new={len(report.new)}, "
+                f"modified={len(report.modified)}, deleted={len(report.deleted)}, "
+                f"moves={len(report.moves)})"
+            )
+            return report
 
     async def sync_file(
         self, path: str, new: bool = True
@@ -590,12 +650,14 @@ class SyncService:
             logger.warning(f"Skipping file due to repeated failures: {path}")
             return None, None
 
-        try:
-            logger.debug(
-                f"Syncing file path={path} is_new={new} is_markdown={self.file_service.is_markdown(path)}"
-            )
+        start_time = time.time()
+        is_markdown = self.file_service.is_markdown(path)
+        file_kind = "markdown" if is_markdown else "regular"
 
-            if self.file_service.is_markdown(path):
+        try:
+            logger.debug(f"Syncing file path={path} is_new={new} is_markdown={is_markdown}")
+
+            if is_markdown:
                 entity, checksum = await self.sync_markdown_file(path, new)
             else:
                 entity, checksum = await self.sync_regular_file(path, new)
@@ -620,33 +682,63 @@ class SyncService:
                 logger.debug(
                     f"File sync completed, path={path}, entity_id={entity.id}, checksum={checksum[:8]}"
                 )
+            duration_ms = int((time.time() - start_time) * 1000)
+            if duration_ms >= SLOW_FILE_SYNC_WARNING_MS:
+                logger.warning(
+                    f"Slow file sync detected: path={path}, file_kind={file_kind}, duration_ms={duration_ms}"
+                )
             return entity, checksum
 
         except FileNotFoundError:
             # File exists in database but not on filesystem
             # This indicates a database/filesystem inconsistency - treat as deletion
-            logger.warning(
-                f"File not found during sync, treating as deletion: path={path}. "
-                "This may indicate a race condition or manual file deletion."
-            )
-            await self.handle_delete(path)
+            with telemetry.scope(
+                "sync.file.failure",
+                failure_type="file_not_found",
+                path=path,
+                file_kind=file_kind,
+                is_new=new,
+                is_fatal=False,
+            ):
+                logger.warning(
+                    f"File not found during sync, treating as deletion: path={path}. "
+                    "This may indicate a race condition or manual file deletion."
+                )
+                await self.handle_delete(path)
             return None, None
 
         except Exception as e:
+            failure_type = type(e).__name__
             # Check if this is a fatal error (or caused by one)
             # Fatal errors like project deletion should terminate sync immediately
             if isinstance(e, SyncFatalError) or isinstance(
                 e.__cause__, SyncFatalError
             ):  # pragma: no cover
-                logger.error(f"Fatal sync error encountered, terminating sync: path={path}")
+                with telemetry.scope(
+                    "sync.file.failure",
+                    failure_type=failure_type,
+                    path=path,
+                    file_kind=file_kind,
+                    is_new=new,
+                    is_fatal=True,
+                ):
+                    logger.error(f"Fatal sync error encountered, terminating sync: path={path}")
                 raise
 
             # Otherwise treat as recoverable file-level error
             error_msg = str(e)
-            logger.error(f"Failed to sync file: path={path}, error={error_msg}")
+            with telemetry.scope(
+                "sync.file.failure",
+                failure_type=failure_type,
+                path=path,
+                file_kind=file_kind,
+                is_new=new,
+                is_fatal=False,
+            ):
+                logger.error(f"Failed to sync file: path={path}, error={error_msg}")
 
-            # Record failure for circuit breaker
-            await self._record_failure(path, error_msg)
+                # Record failure for circuit breaker
+                await self._record_failure(path, error_msg)
 
             return None, None
 
@@ -1040,24 +1132,36 @@ class SyncService:
                     # update search index only on successful resolution
                     await self.search_service.index_entity(resolved_entity)
                 except IntegrityError:
-                    # IntegrityError means a relation with this (from_id, to_id, relation_type)
-                    # already exists. The UPDATE was rolled back, so our unresolved relation
-                    # (to_id=NULL) still exists in the database. We delete it because:
-                    # 1. It's redundant - a resolved relation already captures this relationship
-                    # 2. If we don't delete it, future syncs will try to resolve it again
-                    #    and get the same IntegrityError
-                    logger.debug(
-                        "Deleting duplicate unresolved relation "
-                        f"relation_id={relation.id} "
-                        f"from_id={relation.from_id} "
-                        f"to_name={relation.to_name} "
-                        f"resolved_to_id={resolved_entity.id}"
-                    )
-                    try:
-                        await self.relation_repository.delete(relation.id)
-                    except Exception as e:
-                        # Log but don't fail - the relation may have been deleted already
-                        logger.debug(f"Could not delete duplicate relation {relation.id}: {e}")
+                    with telemetry.scope(
+                        "sync.relation.resolve_conflict",
+                        relation_id=relation.id,
+                        relation_type=relation.relation_type,
+                    ):
+                        # IntegrityError means a relation with this (from_id, to_id, relation_type)
+                        # already exists. The UPDATE was rolled back, so our unresolved relation
+                        # (to_id=NULL) still exists in the database. We delete it because:
+                        # 1. It's redundant - a resolved version already captures this relationship
+                        # 2. If we don't delete it, future syncs will try to resolve it again
+                        #    and get the same IntegrityError
+                        logger.debug(
+                            "Deleting duplicate unresolved relation "
+                            f"relation_id={relation.id} "
+                            f"from_id={relation.from_id} "
+                            f"to_name={relation.to_name} "
+                            f"resolved_to_id={resolved_entity.id}"
+                        )
+                        try:
+                            await self.relation_repository.delete(relation.id)
+                        except Exception as e:
+                            with telemetry.scope(
+                                "sync.relation.cleanup_failure",
+                                relation_id=relation.id,
+                                relation_type=relation.relation_type,
+                            ):
+                                # Log but don't fail - the relation may have been deleted already
+                                logger.debug(
+                                    f"Could not delete duplicate relation {relation.id}: {e}"
+                                )
 
     async def _quick_count_files(self, directory: Path) -> int:
         """Fast file count using find command.

src/basic_memory/telemetry.py

@@ -0,0 +1,209 @@
+"""Optional Logfire telemetry helpers for Basic Memory.
+
+Telemetry is disabled by default. When enabled, this module configures Logfire,
+exposes a `loguru` handler for trace-aware logging, and provides lightweight
+helpers for manual spans and logger context binding.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Any, Iterator
+
+from loguru import logger
+
+REPOSITORY_URL = "https://github.com/basicmachines-co/basic-memory"
+ROOT_PATH = "src/basic_memory"
+
+
+def _load_logfire() -> Any | None:
+    """Load the optional logfire dependency lazily."""
+    try:
+        import logfire
+    except ImportError:
+        return None
+    return logfire
+
+
+@dataclass
+class TelemetryState:
+    """Process-local Logfire configuration state."""
+
+    enabled: bool = False
+    configured: bool = False
+    service_name: str | None = None
+    environment: str | None = None
+    send_to_logfire: bool = False
+    warnings: list[str] = field(default_factory=list)
+
+
+_STATE = TelemetryState()
+_LOGFIRE_HANDLER: dict[str, Any] | None = None
+_ACTIVE_LOG_CONTEXT: ContextVar[dict[str, Any]] = ContextVar("basic_memory_log_context", default={})
+
+
+def reset_telemetry_state() -> None:
+    """Reset process-local telemetry state.
+
+    Primarily used by tests.
+    """
+    global _LOGFIRE_HANDLER
+    _STATE.enabled = False
+    _STATE.configured = False
+    _STATE.service_name = None
+    _STATE.environment = None
+    _STATE.send_to_logfire = False
+    _STATE.warnings.clear()
+    _LOGFIRE_HANDLER = None
+    _ACTIVE_LOG_CONTEXT.set({})
+
+
+def _filter_attributes(attrs: dict[str, Any]) -> dict[str, Any]:
+    """Drop null attributes so span and log payloads stay compact."""
+    return {key: value for key, value in attrs.items() if value is not None}
+
+
+def _current_log_context() -> dict[str, Any]:
+    """Return the currently active telemetry context for this execution flow."""
+    return dict(_ACTIVE_LOG_CONTEXT.get())
+
+
+def configure_telemetry(
+    service_name: str,
+    *,
+    environment: str,
+    service_version: str | None = None,
+    enable_logfire: bool = False,
+    send_to_logfire: bool = False,
+    log_level: str = "INFO",
+) -> bool:
+    """Configure optional Logfire instrumentation for the current process."""
+    global _LOGFIRE_HANDLER
+
+    reset_telemetry_state()
+    _STATE.service_name = service_name
+    _STATE.environment = environment
+    _STATE.send_to_logfire = send_to_logfire
+    _STATE.enabled = enable_logfire
+
+    if not enable_logfire:
+        return False
+
+    logfire = _load_logfire()
+    if logfire is None:
+        _STATE.enabled = False
+        _STATE.warnings.append(
+            "Logfire telemetry was enabled but the 'logfire' package is not installed. "
+            "Telemetry remains disabled."
+        )
+        return False
+
+    configure_kwargs = {
+        "service_name": service_name,
+        "environment": environment,
+        "code_source": logfire.CodeSource(
+            repository=REPOSITORY_URL,
+            revision=service_version or "",
+            root_path=ROOT_PATH,
+        ),
+        "min_level": log_level.lower(),
+        "send_to_logfire": send_to_logfire,
+    }
+
+    try:
+        logfire.configure(**configure_kwargs)
+    except TypeError:
+        configure_kwargs.pop("send_to_logfire", None)
+        logfire.configure(**configure_kwargs)
+    except Exception as exc:  # pragma: no cover
+        _STATE.enabled = False  # pragma: no cover
+        _STATE.warnings.append(f"Failed to configure Logfire telemetry: {exc}")  # pragma: no cover
+        return False  # pragma: no cover
+
+    _LOGFIRE_HANDLER = logfire.loguru_handler()
+    _STATE.configured = True
+    return True
+
+
+def telemetry_enabled() -> bool:
+    """Return True when telemetry is both enabled and configured."""
+    return _STATE.enabled and _STATE.configured
+
+
+def get_logfire_handler() -> dict[str, Any] | None:
+    """Return the active Logfire `loguru` handler, if any."""
+    return _LOGFIRE_HANDLER
+
+
+def pop_telemetry_warnings() -> list[str]:
+    """Return and clear pending telemetry warnings."""
+    warnings = list(_STATE.warnings)
+    _STATE.warnings.clear()
+    return warnings
+
+
+def bind_telemetry_context(**attrs: Any):
+    """Bind stable telemetry attributes onto the shared Loguru logger."""
+    merged_attrs = _current_log_context()
+    merged_attrs.update(_filter_attributes(attrs))
+    return logger.bind(**merged_attrs)
+
+
+@contextmanager
+def contextualize(**attrs: Any) -> Iterator[None]:
+    """Apply stable telemetry attributes to all Loguru calls in this scope."""
+    filtered_attrs = _filter_attributes(attrs)
+    merged_attrs = _current_log_context()
+    merged_attrs.update(filtered_attrs)
+    context_token = _ACTIVE_LOG_CONTEXT.set(merged_attrs)
+
+    try:
+        with logger.contextualize(**filtered_attrs):
+            yield
+    finally:
+        _ACTIVE_LOG_CONTEXT.reset(context_token)
+
+
+@contextmanager
+def scope(name: str, **attrs: Any) -> Iterator[None]:
+    """Create a span and bind the same stable attributes into Loguru context."""
+    with contextualize(**attrs):
+        with span(name, **attrs):
+            yield
+
+
+# Alias: `operation` signals a root-level boundary (entrypoint, tool invocation),
+# while `scope` signals a nested phase. The distinction is convention only.
+operation = scope
+
+
+@contextmanager
+def span(name: str, **attrs: Any) -> Iterator[None]:
+    """Create a manual Logfire span when telemetry is enabled."""
+    if not telemetry_enabled():
+        yield
+        return
+
+    logfire = _load_logfire()
+    if logfire is None:  # pragma: no cover
+        yield  # pragma: no cover
+        return  # pragma: no cover
+
+    with logfire.span(name, **_filter_attributes(attrs)):
+        yield
+
+
+__all__ = [
+    "bind_telemetry_context",
+    "contextualize",
+    "configure_telemetry",
+    "get_logfire_handler",
+    "operation",
+    "pop_telemetry_warnings",
+    "reset_telemetry_state",
+    "scope",
+    "span",
+    "telemetry_enabled",
+]

src/basic_memory/utils.py

@@ -1,5 +1,6 @@
 """Utility functions for basic-memory."""
 
+import json
 import os
 
 import logging
@@ -7,11 +8,13 @@ import re
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Protocol, Union, runtime_checkable, List, Optional
+from typing import Any, Protocol, Union, runtime_checkable, List, Optional
 
 from loguru import logger
 from unidecode import unidecode
 
+from basic_memory import telemetry
+
 
 def normalize_project_path(path: str) -> str:
     """Normalize project path by stripping mount point prefix.
@@ -66,6 +69,7 @@ class PathLike(Protocol):
 # In type annotations, use Union[Path, str] instead of FilePath for now
 # This preserves compatibility with existing code while we migrate
 FilePath = Union[Path, str]
+WINDOWS_LOG_FILE_RETENTION = 5
 
 
 def generate_permalink(file_path: Union[Path, str, PathLike], split_extension: bool = True) -> str:
@@ -250,7 +254,7 @@ def setup_logging(
     log_to_file: bool = False,
     log_to_stdout: bool = False,
     structured_context: bool = False,
-) -> None:  # pragma: no cover
+) -> None:
     """Configure logging with explicit settings.
 
     This function provides a simple, explicit interface for configuring logging.
@@ -273,8 +277,14 @@ def setup_logging(
 
     # Add file handler with rotation
     if log_to_file:
-        log_path = Path.home() / ".basic-memory" / "basic-memory.log"
+        # Trigger: Windows does not allow renaming an open file held by another process.
+        # Why: multiple basic-memory processes can share the same log directory at once.
+        # Outcome: use per-process log files on Windows so log rotation stays local.
+        log_filename = f"basic-memory-{os.getpid()}.log" if os.name == "nt" else "basic-memory.log"
+        log_path = Path.home() / ".basic-memory" / log_filename
         log_path.parent.mkdir(parents=True, exist_ok=True)
+        if os.name == "nt":
+            _cleanup_windows_log_files(log_path.parent, log_path.name)
         # Keep logging synchronous (enqueue=False) to avoid background logging threads.
         # Background threads are a common source of "hang on exit" issues in CLI/test runs.
         logger.add(
@@ -292,6 +302,11 @@ def setup_logging(
     if log_to_stdout:
         logger.add(sys.stderr, level=log_level, backtrace=True, diagnose=True, colorize=True)
 
+    # Add Logfire sink when telemetry bootstrap enabled it for this process.
+    logfire_handler = telemetry.get_logfire_handler()
+    if logfire_handler is not None:
+        logger.add(**logfire_handler)
+
     # Bind structured context for cloud observability
     if structured_context:
         logger.configure(
@@ -307,6 +322,31 @@ def setup_logging(
     logging.getLogger("httpx").setLevel(logging.WARNING)
     logging.getLogger("watchfiles.main").setLevel(logging.WARNING)
 
+    for warning_message in telemetry.pop_telemetry_warnings():
+        logger.warning(warning_message)
+
+
+def _cleanup_windows_log_files(log_dir: Path, current_log_name: str) -> None:
+    """Trim stale per-process Windows log files so the directory stays bounded."""
+    stale_logs = [
+        path
+        for path in log_dir.glob("basic-memory-*.log*")
+        if path.is_file() and path.name != current_log_name
+    ]
+
+    if len(stale_logs) <= WINDOWS_LOG_FILE_RETENTION - 1:
+        return
+
+    # Trigger: per-process log filenames avoid Windows rename contention but fragment retention.
+    # Why: loguru retention applies per sink, not across the whole basic-memory log directory.
+    # Outcome: keep only the newest stale PID logs so repeated CLI/server launches stay bounded.
+    stale_logs.sort(key=lambda path: path.stat().st_mtime, reverse=True)
+    for stale_log in stale_logs[WINDOWS_LOG_FILE_RETENTION - 1 :]:
+        try:
+            stale_log.unlink()
+        except OSError:
+            logger.debug("Failed to delete stale Windows log file: {path}", path=stale_log)
+
 
 def parse_tags(tags: Union[List[str], str, None]) -> List[str]:
     """Parse tags from various input formats into a consistent list.
@@ -356,6 +396,36 @@ def parse_tags(tags: Union[List[str], str, None]) -> List[str]:
         return []
 
 
+def coerce_list(v: Any) -> Any:
+    """Coerce string input to list for MCP clients that serialize lists as strings."""
+    if v is None:
+        return v
+    if isinstance(v, str):
+        try:
+            parsed = json.loads(v)
+            if isinstance(parsed, list):
+                return parsed
+        except (json.JSONDecodeError, TypeError):
+            pass
+        # Single string value — wrap in a list
+        return [v]
+    return v
+
+
+def coerce_dict(v: Any) -> Any:
+    """Coerce string input to dict for MCP clients that serialize dicts as strings."""
+    if v is None:
+        return v
+    if isinstance(v, str):
+        try:
+            parsed = json.loads(v)
+            if isinstance(parsed, dict):
+                return parsed
+        except (json.JSONDecodeError, TypeError):
+            pass
+    return v
+
+
 def normalize_newlines(multiline: str) -> str:
     """Replace any \r\n, \r, or \n with the native newline.
 
@@ -443,12 +513,23 @@ def valid_project_path_value(path: str):
     if not path:
         return True
 
-    # Check for obvious path traversal patterns first
-    if ".." in path or "~" in path:
+    # Check for tilde (home directory expansion)
+    if "~" in path:
         return False
 
-    # Check for Windows-style path traversal (even on Unix systems)
-    if "\\.." in path or path.startswith("\\"):
+    # Check for ".." as a path segment (path traversal), not as a substring.
+    # Filenames like "hi-everyone..md" are legitimate and must not be blocked.
+    # Also block segments like ".. " and ".. ." because Windows normalizes
+    # trailing dots and spaces away, making them equivalent to "..".
+    segments = path.replace("\\", "/").split("/")
+    if any(
+        seg == ".." or (len(seg) > 2 and seg[:2] == ".." and all(c in ". " for c in seg[2:]))
+        for seg in segments
+    ):
+        return False
+
+    # Check for Windows-style leading backslash
+    if path.startswith("\\"):
         return False
 
     # Block absolute paths (Unix-style starting with / or Windows-style with drive letters)

test-int/cli/test_cli_tool_edit_note_integration.py

@@ -208,7 +208,7 @@ def test_edit_note_replace_section_fails_without_section(
     )
 
     assert result.exit_code != 0
-    assert "section parameter is required for replace_section operation" in result.output
+    assert "section parameter is required for section-based operations" in result.output
 
 
 def test_edit_note_append_creates_nonexistent_note_cli(

test-int/conftest.py

@@ -258,6 +258,8 @@ def config_manager(app_config: BasicMemoryConfig, config_home) -> ConfigManager:
     from basic_memory import config as config_module
 
     config_module._CONFIG_CACHE = None
+    config_module._CONFIG_MTIME = None
+    config_module._CONFIG_SIZE = None
 
     config_manager = ConfigManager()
     # Update its paths to use the test directory

test-int/mcp/test_delete_note_integration.py

@@ -307,8 +307,13 @@ async def test_delete_note_by_file_path(mcp_server, app, test_project):
 
 
 @pytest.mark.asyncio
-async def test_delete_note_case_insensitive(mcp_server, app, test_project):
-    """Test that note deletion is case insensitive for titles."""
+async def test_delete_note_rejects_case_mismatch(mcp_server, app, test_project):
+    """Test that delete_note with wrong case does not fuzzy-match to an existing note.
+
+    Strict resolution (#649) prevents destructive operations from silently
+    resolving to a different note via fuzzy search. Case-mismatched titles
+    should be rejected, not resolved to the nearest match.
+    """
 
     async with Client(mcp_server) as client:
         # Create a note with mixed case
@@ -323,7 +328,7 @@ async def test_delete_note_case_insensitive(mcp_server, app, test_project):
             },
         )
 
-        # Try to delete with different case
+        # Try to delete with different case — should NOT find the note
         delete_result = await client.call_tool(
             "delete_note",
             {
@@ -332,8 +337,28 @@ async def test_delete_note_case_insensitive(mcp_server, app, test_project):
             },
         )
 
-        # Should return True for successful deletion
-        assert "true" in delete_result.content[0].text.lower()
+        # Should return False (not found) — strict mode rejects fuzzy matches
+        assert "false" in delete_result.content[0].text.lower()
+
+        # Verify the note still exists using the exact title
+        read_result = await client.call_tool(
+            "read_note",
+            {
+                "project": test_project.name,
+                "identifier": "CamelCase Note Title",
+            },
+        )
+        assert "Testing case sensitivity" in read_result.content[0].text
+
+        # Delete with exact title should succeed
+        delete_result2 = await client.call_tool(
+            "delete_note",
+            {
+                "project": test_project.name,
+                "identifier": "CamelCase Note Title",
+            },
+        )
+        assert "true" in delete_result2.content[0].text.lower()
 
 
 @pytest.mark.asyncio

test-int/mcp/test_edit_note_integration.py

@@ -710,3 +710,81 @@ async def test_edit_note_using_different_identifiers(mcp_server, app, test_proje
         assert "Edited by title." in content
         assert "Edited by permalink." in content
         assert "Edited by folder/title." in content
+
+
+@pytest.mark.asyncio
+async def test_edit_note_append_autocreate_does_not_fuzzy_match(mcp_server, app, test_project):
+    """Reproduces #649: edit_note append must auto-create, not fuzzy-match to an existing note.
+
+    Creates two notes, then attempts to append to a nonexistent identifier.
+    The tool should create a new note, and neither existing note should be modified.
+    """
+
+    async with Client(mcp_server) as client:
+        # Create two notes that could be fuzzy-matched
+        await client.call_tool(
+            "write_note",
+            {
+                "project": test_project.name,
+                "title": "Routing Test A",
+                "directory": "test",
+                "content": "# Routing Test A\n\nContent A.",
+            },
+        )
+        await client.call_tool(
+            "write_note",
+            {
+                "project": test_project.name,
+                "title": "Routing Test B",
+                "directory": "test",
+                "content": "# Routing Test B\n\nContent B.",
+            },
+        )
+
+        # Attempt to edit a nonexistent note — should error, not silently edit A or B
+        edit_result = await client.call_tool(
+            "edit_note",
+            {
+                "project": test_project.name,
+                "identifier": "Routing Test NONEXISTENT",
+                "operation": "append",
+                "content": "\n\nThis should NOT appear in any note.",
+            },
+        )
+
+        edit_text = edit_result.content[0].text
+        # append to nonexistent creates a new note — verify it did NOT edit A or B
+        assert "Created note (append)" in edit_text
+        assert "fileCreated: true" in edit_text
+
+        # Verify neither A nor B was modified
+        read_a = await client.call_tool(
+            "read_note",
+            {"project": test_project.name, "identifier": "Routing Test A"},
+        )
+        content_a = read_a.content[0].text
+        assert "Content A" in content_a
+        assert "This should NOT appear" not in content_a
+
+        read_b = await client.call_tool(
+            "read_note",
+            {"project": test_project.name, "identifier": "Routing Test B"},
+        )
+        content_b = read_b.content[0].text
+        assert "Content B" in content_b
+        assert "This should NOT appear" not in content_b
+
+        # Now test find_replace on nonexistent — should error
+        edit_result2 = await client.call_tool(
+            "edit_note",
+            {
+                "project": test_project.name,
+                "identifier": "Routing Test NONEXISTENT AGAIN",
+                "operation": "find_replace",
+                "content": "replaced",
+                "find_text": "Content",
+            },
+        )
+
+        error_text = edit_result2.content[0].text
+        assert "Edit Failed" in error_text

test-int/mcp/test_move_note_integration.py

@@ -716,3 +716,56 @@ async def test_move_note_destination_folder_mutually_exclusive(mcp_server, app,
         error_text = move_result.content[0].text
         assert "# Move Failed - Invalid Parameters" in error_text
         assert "Cannot specify both" in error_text
+
+
+@pytest.mark.asyncio
+async def test_move_note_strict_resolution_rejects_fuzzy_match(mcp_server, app, test_project):
+    """move_note must not fuzzy-match a nonexistent identifier to an existing note (#649)."""
+
+    async with Client(mcp_server) as client:
+        # Create two notes that could be fuzzy-matched
+        await client.call_tool(
+            "write_note",
+            {
+                "project": test_project.name,
+                "title": "Move Strict Test A",
+                "directory": "test",
+                "content": "# Move Strict Test A\n\nContent A.",
+            },
+        )
+        await client.call_tool(
+            "write_note",
+            {
+                "project": test_project.name,
+                "title": "Move Strict Test B",
+                "directory": "test",
+                "content": "# Move Strict Test B\n\nContent B.",
+            },
+        )
+
+        # Attempt to move a nonexistent note — should error, not move A or B
+        move_result = await client.call_tool(
+            "move_note",
+            {
+                "project": test_project.name,
+                "identifier": "Move Strict Test NONEXISTENT",
+                "destination_path": "archive/Moved.md",
+            },
+        )
+
+        assert len(move_result.content) == 1
+        error_text = move_result.content[0].text
+        assert "# Move Failed" in error_text
+
+        # Verify neither A nor B was moved
+        read_a = await client.call_tool(
+            "read_note",
+            {"project": test_project.name, "identifier": "Move Strict Test A"},
+        )
+        assert "Content A" in read_a.content[0].text
+
+        read_b = await client.call_tool(
+            "read_note",
+            {"project": test_project.name, "identifier": "Move Strict Test B"},
+        )
+        assert "Content B" in read_b.content[0].text

test-int/mcp/test_string_params_integration.py

@@ -0,0 +1,165 @@
+"""Integration tests for MCP tools accepting string-serialized list/dict params.
+
+Goes through the full FastMCP Client → validate_call → tool function path,
+which is where Pydantic rejects strings for list/dict params.
+"""
+
+import pytest
+from fastmcp import Client
+
+
+@pytest.mark.asyncio
+async def test_search_notes_entity_types_as_string(mcp_server, app, test_project):
+    """search_notes should accept entity_types as a JSON string via MCP protocol."""
+    async with Client(mcp_server) as client:
+        await client.call_tool(
+            "write_note",
+            {
+                "project": test_project.name,
+                "title": "Entity Type Coerce Test",
+                "directory": "test",
+                "content": "# Test\nContent for entity type coercion",
+            },
+        )
+
+        # MCP client sends entity_types as a string
+        result = await client.call_tool(
+            "search_notes",
+            {
+                "project": test_project.name,
+                "query": "coercion",
+                "entity_types": '["entity"]',
+            },
+        )
+        text = result.content[0].text
+        assert "Search Failed" not in text
+
+
+@pytest.mark.asyncio
+async def test_search_notes_note_types_as_string(mcp_server, app, test_project):
+    """search_notes should accept note_types as a JSON string via MCP protocol."""
+    async with Client(mcp_server) as client:
+        await client.call_tool(
+            "write_note",
+            {
+                "project": test_project.name,
+                "title": "Note Type Coerce Test",
+                "directory": "test",
+                "content": "# Test\nContent for note type coercion",
+            },
+        )
+
+        result = await client.call_tool(
+            "search_notes",
+            {
+                "project": test_project.name,
+                "query": "coercion",
+                "note_types": '["note"]',
+            },
+        )
+        text = result.content[0].text
+        assert "Search Failed" not in text
+
+
+@pytest.mark.asyncio
+async def test_search_notes_tags_as_string(mcp_server, app, test_project):
+    """search_notes should accept tags as a JSON string via MCP protocol."""
+    async with Client(mcp_server) as client:
+        await client.call_tool(
+            "write_note",
+            {
+                "project": test_project.name,
+                "title": "Tags Coerce Test",
+                "directory": "test",
+                "content": "# Test\nTagged content for coercion",
+                "tags": "alpha",
+            },
+        )
+
+        result = await client.call_tool(
+            "search_notes",
+            {
+                "project": test_project.name,
+                "query": "tagged",
+                "tags": '["alpha"]',
+            },
+        )
+        text = result.content[0].text
+        assert "Search Failed" not in text
+
+
+@pytest.mark.asyncio
+async def test_search_notes_metadata_filters_as_string(mcp_server, app, test_project):
+    """search_notes should accept metadata_filters as a JSON string via MCP protocol."""
+    async with Client(mcp_server) as client:
+        await client.call_tool(
+            "write_note",
+            {
+                "project": test_project.name,
+                "title": "Metadata Coerce Test",
+                "directory": "test",
+                "content": "# Test\nMetadata content for coercion",
+            },
+        )
+
+        result = await client.call_tool(
+            "search_notes",
+            {
+                "project": test_project.name,
+                "query": "metadata",
+                "metadata_filters": '{"type": "note"}',
+            },
+        )
+        text = result.content[0].text
+        assert "Search Failed" not in text
+
+
+@pytest.mark.asyncio
+async def test_write_note_metadata_as_string(mcp_server, app, test_project):
+    """write_note should accept metadata as a JSON string via MCP protocol."""
+    async with Client(mcp_server) as client:
+        result = await client.call_tool(
+            "write_note",
+            {
+                "project": test_project.name,
+                "title": "String Metadata Note",
+                "directory": "test",
+                "content": "# Test\nWith string metadata",
+                "metadata": '{"priority": "high"}',
+            },
+        )
+        text = result.content[0].text
+        assert "Created note" in text or "Updated note" in text
+
+
+@pytest.mark.asyncio
+async def test_canvas_nodes_edges_as_string(mcp_server, app, test_project):
+    """canvas should accept nodes and edges as JSON strings via MCP protocol."""
+    import json
+
+    nodes = [
+        {
+            "id": "n1",
+            "type": "text",
+            "text": "Hello",
+            "x": 0,
+            "y": 0,
+            "width": 200,
+            "height": 100,
+        }
+    ]
+    edges = [{"id": "e1", "fromNode": "n1", "toNode": "n1", "label": "self"}]
+
+    async with Client(mcp_server) as client:
+        result = await client.call_tool(
+            "canvas",
+            {
+                "project": test_project.name,
+                "title": "Coerce Canvas Test",
+                "directory": "test",
+                "nodes": json.dumps(nodes),
+                "edges": json.dumps(edges),
+            },
+        )
+        text = result.content[0].text
+        assert "Created" in text or "Updated" in text

tests/api/v2/test_search_router_telemetry.py

@@ -0,0 +1,62 @@
+"""Telemetry coverage for the v2 search router."""
+
+from __future__ import annotations
+
+import importlib
+from contextlib import contextmanager
+
+import pytest
+
+from basic_memory.schemas.search import SearchQuery
+
+search_router_module = importlib.import_module("basic_memory.api.v2.routers.search_router")
+
+
+@pytest.mark.asyncio
+async def test_search_router_wraps_request_in_manual_operation() -> None:
+    operations: list[tuple[str, dict]] = []
+
+    class FakeSearchService:
+        async def search(self, query, *, limit, offset):
+            return []
+
+    @contextmanager
+    def fake_operation(name: str, **attrs):
+        operations.append((name, attrs))
+        yield
+
+    async def fake_to_search_results(entity_service, results):
+        return []
+
+    original_operation = search_router_module.telemetry.operation
+    original_to_search_results = search_router_module.to_search_results
+    search_router_module.telemetry.operation = fake_operation
+    search_router_module.to_search_results = fake_to_search_results
+    try:
+        response = await search_router_module.search(
+            SearchQuery(text="hello world"),
+            FakeSearchService(),
+            object(),
+            project_id="project-123",
+            page=2,
+            page_size=5,
+        )
+    finally:
+        search_router_module.telemetry.operation = original_operation
+        search_router_module.to_search_results = original_to_search_results
+
+    assert response.current_page == 2
+    assert operations == [
+        (
+            "api.request.search",
+            {
+                "entrypoint": "api",
+                "page": 2,
+                "page_size": 5,
+                "retrieval_mode": "fts",
+                "has_text_query": True,
+                "has_title_query": False,
+                "has_permalink_query": False,
+            },
+        )
+    ]

tests/cli/cloud/test_cloud_api_client_and_utils.py

@@ -163,3 +163,71 @@ async def test_cloud_utils_fetch_and_exists_and_create_project(
     assert created.new_project["name"] == "My Project"
     # Path should be permalink-like (kebab)
     assert seen["create_payload"]["path"] == "my-project"
+
+
+@pytest.mark.asyncio
+async def test_make_api_request_prefers_api_key_over_oauth(config_home, config_manager):
+    """API key in config should be used without needing an OAuth token on disk."""
+    # Arrange: set an API key in config, no OAuth token on disk
+    config = config_manager.load_config()
+    config.cloud_api_key = "bmc_test_key_12345"
+    config_manager.save_config(config)
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        # Verify the API key is sent as the Bearer token
+        assert request.headers.get("authorization") == "Bearer bmc_test_key_12345"
+        return httpx.Response(200, json={"ok": True})
+
+    transport = httpx.MockTransport(handler)
+
+    @asynccontextmanager
+    async def http_client_factory():
+        async with httpx.AsyncClient(transport=transport) as client:
+            yield client
+
+    # Act — no auth= parameter, no OAuth token file; should use API key from config
+    resp = await make_api_request(
+        method="GET",
+        url="https://cloud.example.test/proxy/health",
+        http_client_factory=http_client_factory,
+    )
+
+    # Assert
+    assert resp.json()["ok"] is True
+
+
+@pytest.mark.asyncio
+async def test_make_api_request_falls_back_to_oauth_when_no_api_key(config_home, config_manager):
+    """When no API key is configured, should fall back to OAuth token."""
+    # Arrange: no API key, but OAuth token on disk
+    config = config_manager.load_config()
+    config.cloud_api_key = None
+    config_manager.save_config(config)
+
+    auth = CLIAuth(client_id="cid", authkit_domain="https://auth.example.test")
+    auth.token_file.parent.mkdir(parents=True, exist_ok=True)
+    auth.token_file.write_text(
+        '{"access_token":"oauth-token-456","refresh_token":null,'
+        '"expires_at":9999999999,"token_type":"Bearer"}',
+        encoding="utf-8",
+    )
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        assert request.headers.get("authorization") == "Bearer oauth-token-456"
+        return httpx.Response(200, json={"ok": True})
+
+    transport = httpx.MockTransport(handler)
+
+    @asynccontextmanager
+    async def http_client_factory():
+        async with httpx.AsyncClient(transport=transport) as client:
+            yield client
+
+    resp = await make_api_request(
+        method="GET",
+        url="https://cloud.example.test/proxy/health",
+        auth=auth,
+        http_client_factory=http_client_factory,
+    )
+
+    assert resp.json()["ok"] is True

tests/cli/conftest.py

@@ -25,6 +25,8 @@ def isolated_home(tmp_path, monkeypatch) -> Path:
     from basic_memory import config as config_module
 
     config_module._CONFIG_CACHE = None
+    config_module._CONFIG_MTIME = None
+    config_module._CONFIG_SIZE = None
 
     monkeypatch.setenv("HOME", str(tmp_path))
     if os.name == "nt":

tests/cli/test_auto_update.py

@@ -0,0 +1,399 @@
+"""Tests for CLI auto-update behavior."""
+
+from __future__ import annotations
+
+import subprocess
+from datetime import datetime, timedelta, timezone
+from io import StringIO
+
+from rich.console import Console
+
+from basic_memory.cli.auto_update import (
+    AutoUpdateResult,
+    AutoUpdateStatus,
+    InstallSource,
+    _check_homebrew_update_available,
+    _is_interactive_session,
+    detect_install_source,
+    maybe_run_periodic_auto_update,
+    run_auto_update,
+)
+from basic_memory.config import BasicMemoryConfig
+
+
+class StubConfigManager:
+    """Simple in-memory ConfigManager stub for updater tests."""
+
+    def __init__(self, config: BasicMemoryConfig):
+        self._config = config
+        self.save_calls = 0
+
+    def load_config(self) -> BasicMemoryConfig:
+        return self._config
+
+    def save_config(self, config: BasicMemoryConfig) -> None:
+        self._config = config
+        self.save_calls += 1
+
+
+def _capture_console() -> tuple[Console, StringIO]:
+    """Create a Console that writes to an in-memory buffer."""
+    buf = StringIO()
+    return Console(file=buf, force_terminal=True), buf
+
+
+def _base_config(tmp_path) -> BasicMemoryConfig:
+    return BasicMemoryConfig(projects={"main": {"path": str(tmp_path / "main")}})
+
+
+def _result(
+    status: AutoUpdateStatus,
+    *,
+    message: str | None,
+    error: str | None = None,
+) -> AutoUpdateResult:
+    return AutoUpdateResult(
+        status=status,
+        source=InstallSource.UV_TOOL,
+        checked=True,
+        update_available=status in {AutoUpdateStatus.UPDATE_AVAILABLE, AutoUpdateStatus.UPDATED},
+        updated=status == AutoUpdateStatus.UPDATED,
+        latest_version="9.9.9",
+        message=message,
+        error=error,
+        restart_recommended=status == AutoUpdateStatus.UPDATED,
+    )
+
+
+def test_detect_install_source_variants():
+    assert (
+        detect_install_source("/opt/homebrew/Cellar/basic-memory/0.18.0/bin/python")
+        == InstallSource.HOMEBREW
+    )
+    assert (
+        detect_install_source("/Users/me/.local/share/uv/tools/basic-memory/bin/python")
+        == InstallSource.UV_TOOL
+    )
+    assert (
+        detect_install_source("/Users/me/.cache/uv/archive-v0/abc123/bin/python")
+        == InstallSource.UVX
+    )
+    assert (
+        detect_install_source("/Users/me/Library/Caches/uv/archive-v0/abc123/bin/python")
+        == InstallSource.UVX
+    )
+    assert detect_install_source("/usr/local/bin/python3") == InstallSource.UNKNOWN
+
+
+def test_interval_gate_skips_check_when_recent(tmp_path):
+    config = _base_config(tmp_path)
+    config.auto_update_last_checked_at = datetime.now() - timedelta(seconds=30)
+    config.update_check_interval = 3600
+    manager = StubConfigManager(config)
+
+    result = run_auto_update(config_manager=manager)
+
+    assert result.status == AutoUpdateStatus.SKIPPED
+    assert result.checked is False
+    assert manager.save_calls == 0
+
+
+def test_auto_update_disabled_skips_periodic(tmp_path):
+    config = _base_config(tmp_path)
+    config.auto_update = False
+    manager = StubConfigManager(config)
+
+    result = run_auto_update(config_manager=manager)
+
+    assert result.status == AutoUpdateStatus.SKIPPED
+    assert result.checked is False
+
+
+def test_force_bypasses_auto_update_disabled(monkeypatch, tmp_path):
+    config = _base_config(tmp_path)
+    config.auto_update = False
+    manager = StubConfigManager(config)
+
+    monkeypatch.setattr(
+        "basic_memory.cli.auto_update._check_pypi_update_available",
+        lambda: (False, "0.0.0"),
+    )
+
+    result = run_auto_update(
+        force=True,
+        config_manager=manager,
+        executable="/Users/me/.local/share/uv/tools/basic-memory/bin/python",
+    )
+
+    assert result.status == AutoUpdateStatus.UP_TO_DATE
+    assert result.checked is True
+    assert manager.save_calls == 1
+
+
+def test_check_homebrew_update_available_exit_code_1_means_outdated(monkeypatch):
+    """brew outdated exits 1 when the formula is outdated, not on error."""
+
+    def _fake_run(command, **kwargs):
+        return subprocess.CompletedProcess(
+            command, 1, stdout="basicmachines-co/basic-memory/basic-memory\n", stderr=""
+        )
+
+    monkeypatch.setattr("basic_memory.cli.auto_update._run_subprocess", _fake_run)
+    is_outdated, _ = _check_homebrew_update_available(silent=False)
+    assert is_outdated is True
+
+
+def test_check_homebrew_update_available_exit_code_0_means_up_to_date(monkeypatch):
+    """brew outdated exits 0 when the formula is up to date."""
+
+    def _fake_run(command, **kwargs):
+        return subprocess.CompletedProcess(command, 0, stdout="", stderr="")
+
+    monkeypatch.setattr("basic_memory.cli.auto_update._run_subprocess", _fake_run)
+    is_outdated, _ = _check_homebrew_update_available(silent=False)
+    assert is_outdated is False
+
+
+def test_homebrew_outdated_triggers_upgrade(monkeypatch, tmp_path):
+    config = _base_config(tmp_path)
+    manager = StubConfigManager(config)
+
+    monkeypatch.setattr(
+        "basic_memory.cli.auto_update._check_homebrew_update_available",
+        lambda silent: (True, None),
+    )
+    calls: list[list[str]] = []
+
+    def _fake_run_subprocess(command, **kwargs):
+        calls.append(command)
+        return subprocess.CompletedProcess(command, 0, stdout="", stderr="")
+
+    monkeypatch.setattr("basic_memory.cli.auto_update._run_subprocess", _fake_run_subprocess)
+
+    result = run_auto_update(
+        config_manager=manager,
+        executable="/opt/homebrew/Cellar/basic-memory/0.18.0/bin/python",
+    )
+
+    assert result.status == AutoUpdateStatus.UPDATED
+    assert calls == [["brew", "upgrade", "basic-memory"]]
+
+
+def test_uv_tool_pypi_check_triggers_upgrade(monkeypatch, tmp_path):
+    config = _base_config(tmp_path)
+    manager = StubConfigManager(config)
+
+    monkeypatch.setattr(
+        "basic_memory.cli.auto_update._check_pypi_update_available",
+        lambda: (True, "9.9.9"),
+    )
+    calls: list[list[str]] = []
+
+    def _fake_run_subprocess(command, **kwargs):
+        calls.append(command)
+        return subprocess.CompletedProcess(command, 0, stdout="", stderr="")
+
+    monkeypatch.setattr("basic_memory.cli.auto_update._run_subprocess", _fake_run_subprocess)
+
+    result = run_auto_update(
+        config_manager=manager,
+        executable="/Users/me/.local/share/uv/tools/basic-memory/bin/python",
+    )
+
+    assert result.status == AutoUpdateStatus.UPDATED
+    assert result.latest_version == "9.9.9"
+    assert calls == [["uv", "tool", "upgrade", "basic-memory"]]
+
+
+def test_unknown_manager_returns_manual_update_guidance(monkeypatch, tmp_path):
+    config = _base_config(tmp_path)
+    manager = StubConfigManager(config)
+    monkeypatch.setattr(
+        "basic_memory.cli.auto_update._check_pypi_update_available",
+        lambda: (True, "9.9.9"),
+    )
+
+    result = run_auto_update(
+        force=True,
+        config_manager=manager,
+        executable="/usr/local/bin/python3",
+    )
+
+    assert result.status == AutoUpdateStatus.UPDATE_AVAILABLE
+    assert result.updated is False
+    assert "Automatic install is not supported" in (result.message or "")
+
+
+def test_uvx_runtime_is_skipped(monkeypatch, tmp_path):
+    config = _base_config(tmp_path)
+    manager = StubConfigManager(config)
+
+    result = run_auto_update(
+        config_manager=manager,
+        executable="/Users/me/.cache/uv/archive-v0/abc123/bin/python",
+    )
+
+    assert result.status == AutoUpdateStatus.SKIPPED
+    assert result.source == InstallSource.UVX
+    assert result.checked is False
+    assert manager.save_calls == 0
+
+
+def test_mcp_silent_mode_suppresses_subprocess_output(monkeypatch, tmp_path):
+    config = _base_config(tmp_path)
+    manager = StubConfigManager(config)
+    monkeypatch.setattr(
+        "basic_memory.cli.auto_update._check_pypi_update_available",
+        lambda: (True, "9.9.9"),
+    )
+
+    captured_kwargs: list[dict] = []
+
+    def _fake_run_subprocess(command, **kwargs):
+        captured_kwargs.append(kwargs)
+        return subprocess.CompletedProcess(command, 0, stdout="", stderr="")
+
+    monkeypatch.setattr("basic_memory.cli.auto_update._run_subprocess", _fake_run_subprocess)
+
+    result = run_auto_update(
+        config_manager=manager,
+        executable="/Users/me/.local/share/uv/tools/basic-memory/bin/python",
+        silent=True,
+    )
+
+    assert result.status == AutoUpdateStatus.UPDATED
+    assert captured_kwargs
+    assert captured_kwargs[0]["silent"] is True
+    assert captured_kwargs[0]["capture_output"] is False
+
+
+def test_subprocess_oserror_is_non_fatal(monkeypatch, tmp_path):
+    config = _base_config(tmp_path)
+    manager = StubConfigManager(config)
+    monkeypatch.setattr(
+        "basic_memory.cli.auto_update._check_pypi_update_available",
+        lambda: (True, "9.9.9"),
+    )
+
+    def _raise_oserror(command, **kwargs):
+        raise FileNotFoundError(command[0])
+
+    monkeypatch.setattr("basic_memory.cli.auto_update._run_subprocess", _raise_oserror)
+
+    result = run_auto_update(
+        config_manager=manager,
+        executable="/Users/me/.local/share/uv/tools/basic-memory/bin/python",
+    )
+
+    assert result.status == AutoUpdateStatus.FAILED
+    assert result.checked is True
+
+
+def test_mixed_timezone_timestamp_does_not_crash_interval_gate(monkeypatch, tmp_path):
+    config = _base_config(tmp_path)
+    config.auto_update_last_checked_at = datetime.now(timezone.utc)
+    manager = StubConfigManager(config)
+
+    monkeypatch.setattr(
+        "basic_memory.cli.auto_update._check_pypi_update_available",
+        lambda: (False, "0.0.0"),
+    )
+
+    result = run_auto_update(
+        config_manager=manager,
+        executable="/Users/me/.local/share/uv/tools/basic-memory/bin/python",
+    )
+
+    assert result.status == AutoUpdateStatus.UP_TO_DATE
+    assert result.checked is True
+
+
+def test_maybe_run_periodic_auto_update_non_interactive_has_no_console_output():
+    console, buf = _capture_console()
+    result = maybe_run_periodic_auto_update(
+        "status",
+        is_interactive=False,
+        console=console,
+    )
+    assert result is None
+    assert buf.getvalue() == ""
+
+
+def test_maybe_run_periodic_auto_update_prints_updated(monkeypatch):
+    console, buf = _capture_console()
+    monkeypatch.setattr(
+        "basic_memory.cli.auto_update.run_auto_update",
+        lambda **kwargs: _result(
+            AutoUpdateStatus.UPDATED,
+            message="Basic Memory was updated successfully.",
+        ),
+    )
+
+    result = maybe_run_periodic_auto_update("status", is_interactive=True, console=console)
+    assert result is not None
+    assert result.status == AutoUpdateStatus.UPDATED
+    assert "updated successfully" in buf.getvalue().lower()
+
+
+def test_maybe_run_periodic_auto_update_prints_available(monkeypatch):
+    console, buf = _capture_console()
+    monkeypatch.setattr(
+        "basic_memory.cli.auto_update.run_auto_update",
+        lambda **kwargs: _result(
+            AutoUpdateStatus.UPDATE_AVAILABLE,
+            message="Update available (latest: 9.9.9).",
+        ),
+    )
+
+    result = maybe_run_periodic_auto_update("status", is_interactive=True, console=console)
+    assert result is not None
+    assert result.status == AutoUpdateStatus.UPDATE_AVAILABLE
+    assert "update available" in buf.getvalue().lower()
+
+
+def test_maybe_run_periodic_auto_update_prints_failed_with_error(monkeypatch):
+    console, buf = _capture_console()
+    monkeypatch.setattr(
+        "basic_memory.cli.auto_update.run_auto_update",
+        lambda **kwargs: _result(
+            AutoUpdateStatus.FAILED,
+            message="Automatic update check failed.",
+            error="network timeout",
+        ),
+    )
+
+    result = maybe_run_periodic_auto_update("status", is_interactive=True, console=console)
+    assert result is not None
+    assert result.status == AutoUpdateStatus.FAILED
+    output = buf.getvalue().lower()
+    assert "automatic update check failed" in output
+    assert "network timeout" in output
+
+
+def test_maybe_run_periodic_auto_update_uses_interactive_probe_when_not_overridden(monkeypatch):
+    console, buf = _capture_console()
+    monkeypatch.setattr("basic_memory.cli.auto_update._is_interactive_session", lambda: True)
+    monkeypatch.setattr(
+        "basic_memory.cli.auto_update.run_auto_update",
+        lambda **kwargs: _result(
+            AutoUpdateStatus.UP_TO_DATE,
+            message="Basic Memory is up to date.",
+        ),
+    )
+
+    result = maybe_run_periodic_auto_update("status", console=console)
+    assert result is not None
+    assert result.status == AutoUpdateStatus.UP_TO_DATE
+    # UP_TO_DATE is intentionally silent for periodic checks.
+    assert buf.getvalue() == ""
+
+
+def test_is_interactive_session_handles_closed_stdio(monkeypatch):
+    class _BrokenStream:
+        def isatty(self) -> bool:
+            raise ValueError("I/O operation on closed file")
+
+    monkeypatch.setattr("basic_memory.cli.auto_update.sys.stdin", _BrokenStream())
+    monkeypatch.setattr("basic_memory.cli.auto_update.sys.stdout", _BrokenStream())
+
+    assert _is_interactive_session() is False

tests/cli/test_cli_telemetry.py

@@ -0,0 +1,49 @@
+"""Telemetry coverage for CLI command boundaries."""
+
+from __future__ import annotations
+
+from basic_memory.cli import app as cli_app
+
+
+class FakeContext:
+    """Small Typer-like context for callback testing."""
+
+    def __init__(self, invoked_subcommand: str | None) -> None:
+        self.invoked_subcommand = invoked_subcommand
+        self.resources: list[object] = []
+        self.close_callbacks: list[object] = []
+
+    def with_resource(self, resource: object) -> None:
+        self.resources.append(resource)
+
+    def call_on_close(self, callback) -> None:
+        self.close_callbacks.append(callback)
+
+
+def test_app_callback_registers_command_operation(monkeypatch) -> None:
+    operations: list[tuple[str, dict]] = []
+    resource = object()
+
+    monkeypatch.setattr(cli_app, "init_cli_logging", lambda: None)
+    monkeypatch.setattr(cli_app.CliContainer, "create", staticmethod(lambda: object()))
+    monkeypatch.setattr(cli_app, "set_container", lambda container: None)
+    monkeypatch.setattr(cli_app, "maybe_show_init_line", lambda command_name: None)
+    monkeypatch.setattr(cli_app, "maybe_show_cloud_promo", lambda command_name: None)
+    monkeypatch.setattr(cli_app, "maybe_run_periodic_auto_update", lambda command_name: None)
+
+    def fake_operation(name: str, **attrs):
+        operations.append((name, attrs))
+        return resource
+
+    monkeypatch.setattr(cli_app.telemetry, "operation", fake_operation)
+
+    ctx = FakeContext(invoked_subcommand="status")
+    cli_app.app_callback(ctx, version=None)
+
+    assert ctx.resources == [resource]
+    assert operations == [
+        (
+            "cli.command.status",
+            {"entrypoint": "cli", "command_name": "status"},
+        )
+    ]

tests/cli/test_json_output.py

@@ -350,6 +350,8 @@ def write_config(tmp_path, monkeypatch):
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         config_dir = tmp_path / ".basic-memory"
         config_dir.mkdir(parents=True, exist_ok=True)

tests/cli/test_project_add_with_local_path.py

@@ -27,6 +27,8 @@ def mock_config(tmp_path, monkeypatch):
     from basic_memory import config as config_module
 
     config_module._CONFIG_CACHE = None
+    config_module._CONFIG_MTIME = None
+    config_module._CONFIG_SIZE = None
 
     config_dir = tmp_path / ".basic-memory"
     config_dir.mkdir(parents=True, exist_ok=True)

tests/cli/test_project_list_and_ls.py

@@ -29,6 +29,8 @@ def write_config(tmp_path, monkeypatch):
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         config_dir = tmp_path / ".basic-memory"
         config_dir.mkdir(parents=True, exist_ok=True)
@@ -122,15 +124,16 @@ def test_project_list_shows_local_cloud_presence_and_routes(
     assert "Local Path" in result.stdout
     assert "Cloud Path" in result.stdout
     assert "CLI Route" in result.stdout
-    assert "MCP (stdio)" in result.stdout
+    assert "MCP" in result.stdout
 
     lines = result.stdout.splitlines()
     alpha_line = next(line for line in lines if "│ alpha" in line)
     beta_line = next(line for line in lines if "│ beta" in line)
 
     assert "local" in alpha_line  # CLI route for alpha
+    assert "stdio" in alpha_line  # Local projects use stdio transport
     assert "cloud" in beta_line  # CLI route for beta
-    assert "n/a" in beta_line  # MCP stdio route is unavailable for cloud-only projects
+    assert "https" in beta_line  # Cloud projects use HTTPS transport
     assert "alpha-local" in result.stdout
     assert "/alpha" in result.stdout
     assert "/beta" in result.stdout

tests/cli/test_project_set_cloud_local.py

@@ -22,6 +22,8 @@ def mock_config(tmp_path, monkeypatch):
     from basic_memory import config as config_module
 
     config_module._CONFIG_CACHE = None
+    config_module._CONFIG_MTIME = None
+    config_module._CONFIG_SIZE = None
 
     config_dir = tmp_path / ".basic-memory"
     config_dir.mkdir(parents=True, exist_ok=True)
@@ -68,6 +70,8 @@ class TestSetCloud:
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         config_dir = tmp_path / ".basic-memory"
         config_dir.mkdir(parents=True, exist_ok=True)
@@ -91,6 +95,8 @@ class TestSetCloud:
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         config_dir = tmp_path / ".basic-memory"
         config_dir.mkdir(parents=True, exist_ok=True)
@@ -161,11 +167,15 @@ class TestSetLocal:
 
         # Manually set workspace_id on the project
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
         config_data = json.loads(mock_config.read_text())
         config_data["projects"]["research"]["mode"] = "cloud"
         config_data["projects"]["research"]["workspace_id"] = "11111111-1111-1111-1111-111111111111"
         mock_config.write_text(json.dumps(config_data, indent=2))
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         # Set back to local
         result = runner.invoke(app, ["project", "set-local", "research"])
@@ -173,6 +183,8 @@ class TestSetLocal:
 
         # Verify workspace_id was cleared
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
         updated_data = json.loads(mock_config.read_text())
         assert updated_data["projects"]["research"]["workspace_id"] is None
         assert updated_data["projects"]["research"]["mode"] == "local"
@@ -187,6 +199,8 @@ class TestSetCloudWithWorkspace:
         from basic_memory.schemas.cloud import WorkspaceInfo
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         async def fake_get_available_workspaces():
             return [
@@ -210,6 +224,8 @@ class TestSetCloudWithWorkspace:
 
         # Verify workspace_id was persisted
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
         updated_data = json.loads(mock_config.read_text())
         assert (
             updated_data["projects"]["research"]["workspace_id"]
@@ -222,6 +238,8 @@ class TestSetCloudWithWorkspace:
         from basic_memory.schemas.cloud import WorkspaceInfo
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         async def fake_get_available_workspaces():
             return [
@@ -249,17 +267,23 @@ class TestSetCloudWithWorkspace:
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         # Set default_workspace in config
         config_data = json.loads(mock_config.read_text())
         config_data["default_workspace"] = "global-default-tenant-id"
         mock_config.write_text(json.dumps(config_data, indent=2))
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         result = runner.invoke(app, ["project", "set-cloud", "research"])
         assert result.exit_code == 0
 
         # Verify workspace_id was set from default
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
         updated_data = json.loads(mock_config.read_text())
         assert updated_data["projects"]["research"]["workspace_id"] == "global-default-tenant-id"

tests/cli/test_update_command.py

@@ -0,0 +1,90 @@
+"""Tests for `bm update` command."""
+
+from typer.testing import CliRunner
+
+from basic_memory.cli.app import app
+from basic_memory.cli.auto_update import AutoUpdateResult, AutoUpdateStatus, InstallSource
+
+
+def _result(
+    status: AutoUpdateStatus,
+    *,
+    message: str | None,
+    error: str | None = None,
+) -> AutoUpdateResult:
+    return AutoUpdateResult(
+        status=status,
+        source=InstallSource.UV_TOOL,
+        checked=True,
+        update_available=status in {AutoUpdateStatus.UPDATE_AVAILABLE, AutoUpdateStatus.UPDATED},
+        updated=status == AutoUpdateStatus.UPDATED,
+        latest_version="9.9.9",
+        message=message,
+        error=error,
+        restart_recommended=status == AutoUpdateStatus.UPDATED,
+    )
+
+
+def test_update_command_applies_upgrade(monkeypatch):
+    runner = CliRunner()
+
+    monkeypatch.setattr(
+        "basic_memory.cli.commands.update.run_auto_update",
+        lambda **kwargs: _result(
+            AutoUpdateStatus.UPDATED,
+            message="Basic Memory was updated successfully.",
+        ),
+    )
+
+    result = runner.invoke(app, ["update"])
+    assert result.exit_code == 0
+    assert "updated successfully" in result.stdout.lower()
+
+
+def test_update_command_check_only_shows_available(monkeypatch):
+    runner = CliRunner()
+
+    monkeypatch.setattr(
+        "basic_memory.cli.commands.update.run_auto_update",
+        lambda **kwargs: _result(
+            AutoUpdateStatus.UPDATE_AVAILABLE,
+            message="Update available (latest: 9.9.9). Run `uv tool upgrade basic-memory`.",
+        ),
+    )
+
+    result = runner.invoke(app, ["update", "--check"])
+    assert result.exit_code == 0
+    assert "update available" in result.stdout.lower()
+
+
+def test_update_command_reports_up_to_date(monkeypatch):
+    runner = CliRunner()
+
+    monkeypatch.setattr(
+        "basic_memory.cli.commands.update.run_auto_update",
+        lambda **kwargs: _result(
+            AutoUpdateStatus.UP_TO_DATE,
+            message="Basic Memory is up to date.",
+        ),
+    )
+
+    result = runner.invoke(app, ["update"])
+    assert result.exit_code == 0
+    assert "up to date" in result.stdout.lower()
+
+
+def test_update_command_failure_exits_nonzero(monkeypatch):
+    runner = CliRunner()
+
+    monkeypatch.setattr(
+        "basic_memory.cli.commands.update.run_auto_update",
+        lambda **kwargs: _result(
+            AutoUpdateStatus.FAILED,
+            message="Automatic update failed.",
+            error="network timeout",
+        ),
+    )
+
+    result = runner.invoke(app, ["update"])
+    assert result.exit_code == 1
+    assert "automatic update failed" in result.stdout.lower()

tests/cli/test_workspace_commands.py

@@ -76,6 +76,8 @@ class TestWorkspaceSetDefault:
         monkeypatch.setenv("HOME", str(temp_path))
         monkeypatch.setenv("BASIC_MEMORY_CONFIG_DIR", str(config_dir))
         basic_memory.config._CONFIG_CACHE = None
+        basic_memory.config._CONFIG_MTIME = None
+        basic_memory.config._CONFIG_SIZE = None
 
         config_manager = ConfigManager()
         test_config = BasicMemoryConfig(
@@ -106,6 +108,8 @@ class TestWorkspaceSetDefault:
 
         # Verify config was updated
         basic_memory.config._CONFIG_CACHE = None
+        basic_memory.config._CONFIG_MTIME = None
+        basic_memory.config._CONFIG_SIZE = None
         config = ConfigManager().config
         assert config.default_workspace == "11111111-1111-1111-1111-111111111111"
 

tests/conftest.py

@@ -88,6 +88,12 @@ def anyio_backend():
     return "asyncio"
 
 
+@pytest.fixture(autouse=True)
+def suppress_logfire_no_config_warning(monkeypatch) -> None:
+    """Keep tests focused on behavior instead of Logfire bootstrap warnings."""
+    monkeypatch.setenv("LOGFIRE_IGNORE_NO_CONFIG", "1")
+
+
 @pytest.fixture
 def project_root() -> Path:
     return Path(__file__).parent.parent
@@ -138,6 +144,8 @@ def config_manager(app_config: BasicMemoryConfig, config_home: Path, monkeypatch
     from basic_memory import config as config_module
 
     config_module._CONFIG_CACHE = None
+    config_module._CONFIG_MTIME = None
+    config_module._CONFIG_SIZE = None
 
     # Create a new ConfigManager that uses the test home directory
     config_manager = ConfigManager()

tests/mcp/test_async_client_telemetry.py

@@ -0,0 +1,46 @@
+"""Telemetry coverage for async client auth failures."""
+
+from __future__ import annotations
+
+import importlib
+from contextlib import contextmanager
+from types import SimpleNamespace
+
+import pytest
+
+async_client_module = importlib.import_module("basic_memory.mcp.async_client")
+
+
+@pytest.mark.asyncio
+async def test_resolve_cloud_token_emits_failure_span(monkeypatch) -> None:
+    spans: list[tuple[str, dict]] = []
+    error_messages: list[str] = []
+
+    class FakeAuth:
+        def __init__(self, client_id: str, authkit_domain: str) -> None:
+            self.client_id = client_id
+            self.authkit_domain = authkit_domain
+
+        async def get_valid_token(self):
+            return None
+
+    @contextmanager
+    def fake_span(name: str, **attrs):
+        spans.append((name, attrs))
+        yield
+
+    monkeypatch.setattr(async_client_module.telemetry, "span", fake_span)
+    monkeypatch.setattr("basic_memory.cli.auth.CLIAuth", FakeAuth)
+    monkeypatch.setattr(async_client_module.logger, "error", error_messages.append)
+
+    config = SimpleNamespace(
+        cloud_api_key=None,
+        cloud_client_id="client-123",
+        cloud_domain="auth.example.com",
+    )
+
+    with pytest.raises(RuntimeError, match="no credentials found"):
+        await async_client_module._resolve_cloud_token(config)
+
+    assert spans == [("routing.resolve_cloud_credentials", {"has_api_key": False})]
+    assert error_messages == ["Cloud routing requested but no credentials were available"]

tests/mcp/test_project_context.py

@@ -31,6 +31,7 @@ async def test_returns_none_when_no_default_and_no_project(config_manager, monke
     config_manager.save_config(cfg)
 
     monkeypatch.delenv("BASIC_MEMORY_MCP_PROJECT", raising=False)
+
     # Prevent API fallback from returning a project via stale dependency overrides
     async def _no_api_fallback():
         return None
@@ -93,6 +94,26 @@ async def test_uses_explicit_project_when_no_env(config_manager, monkeypatch):
     assert await resolve_project_parameter(project="explicit-project") == "explicit-project"
 
 
+@pytest.mark.asyncio
+async def test_canonicalizes_case_insensitive_project_reference(
+    config_manager, config_home, monkeypatch
+):
+    from basic_memory.config import ProjectEntry
+    from basic_memory.mcp.project_context import resolve_project_parameter
+
+    cfg = config_manager.load_config()
+    project_name = "Personal-Project"
+    project_path = config_home / "personal-project"
+    project_path.mkdir(parents=True, exist_ok=True)
+    cfg.projects[project_name] = ProjectEntry(path=str(project_path))
+    config_manager.save_config(cfg)
+
+    monkeypatch.delenv("BASIC_MEMORY_MCP_PROJECT", raising=False)
+
+    assert await resolve_project_parameter(project="personal-project") == project_name
+    assert await resolve_project_parameter(project="PERSONAL-PROJECT") == project_name
+
+
 @pytest.mark.asyncio
 async def test_uses_default_project(config_manager, config_home, monkeypatch):
     from basic_memory.mcp.project_context import resolve_project_parameter
@@ -117,6 +138,7 @@ async def test_returns_none_when_no_default(config_manager, monkeypatch):
     config_manager.save_config(cfg)
 
     monkeypatch.delenv("BASIC_MEMORY_MCP_PROJECT", raising=False)
+
     # Prevent API fallback from returning a project via stale dependency overrides
     async def _no_api_fallback():
         return None
@@ -361,6 +383,7 @@ class TestDetectProjectFromUrlPrefix:
         assert result == "My Research"
 
 
+
 class TestGetProjectClientRoutingOrder:
     """Test that get_project_client respects explicit routing before workspace resolution."""
 

tests/mcp/test_project_context_telemetry.py

@@ -0,0 +1,94 @@
+"""Telemetry coverage for project routing helpers."""
+
+from __future__ import annotations
+
+import importlib
+from contextlib import contextmanager
+
+import pytest
+
+from basic_memory.config import ProjectEntry
+from basic_memory.schemas.cloud import WorkspaceInfo
+
+project_context = importlib.import_module("basic_memory.mcp.project_context")
+
+
+class _ContextState:
+    """Minimal FastMCP context-state stub for unit tests."""
+
+    def __init__(self) -> None:
+        self._state: dict[str, object] = {}
+
+    async def get_state(self, key: str):
+        return self._state.get(key)
+
+    async def set_state(self, key: str, value: object, **kwargs) -> None:
+        self._state[key] = value
+
+
+def _capture_telemetry():
+    spans: list[tuple[str, dict]] = []
+    contexts: list[dict] = []
+
+    @contextmanager
+    def fake_span(name: str, **attrs):
+        spans.append((name, attrs))
+        yield
+
+    @contextmanager
+    def fake_contextualize(**attrs):
+        contexts.append(attrs)
+        yield
+
+    return spans, contexts, fake_span, fake_contextualize
+
+
+@pytest.mark.asyncio
+async def test_resolve_workspace_parameter_emits_routing_span(monkeypatch) -> None:
+    spans, _, fake_span, _ = _capture_telemetry()
+    context = _ContextState()
+    workspace = WorkspaceInfo(
+        tenant_id="11111111-1111-1111-1111-111111111111",
+        workspace_type="personal",
+        name="Personal",
+        role="owner",
+    )
+
+    async def fake_get_available_workspaces(context=None):
+        return [workspace]
+
+    monkeypatch.setattr(project_context.telemetry, "span", fake_span)
+    monkeypatch.setattr(project_context, "get_available_workspaces", fake_get_available_workspaces)
+
+    resolved = await project_context.resolve_workspace_parameter(context=context)
+
+    assert resolved.tenant_id == workspace.tenant_id
+    assert spans == [
+        (
+            "routing.resolve_workspace",
+            {"workspace_requested": False, "has_context": True},
+        )
+    ]
+
+
+@pytest.mark.asyncio
+async def test_get_project_client_contextualizes_route_mode(config_manager, monkeypatch) -> None:
+    spans, contexts, fake_span, fake_contextualize = _capture_telemetry()
+
+    config = config_manager.load_config()
+    (config_manager.config_dir.parent / "main").mkdir(parents=True, exist_ok=True)
+    config.projects["main"] = ProjectEntry(path=str(config_manager.config_dir.parent / "main"))
+    config_manager.save_config(config)
+
+    monkeypatch.setattr(project_context.telemetry, "span", fake_span)
+    monkeypatch.setattr(project_context.telemetry, "contextualize", fake_contextualize)
+
+    with pytest.raises(Exception):
+        async with project_context.get_project_client(project="main"):
+            pass
+
+    span_names = [name for name, _ in spans]
+    assert "routing.resolve_project" in span_names
+    assert "routing.client_session" in span_names
+    assert "routing.validate_project" in span_names
+    assert {"project_name": "main", "route_mode": "local_asgi"} in contexts

tests/mcp/test_server_telemetry.py

@@ -0,0 +1,33 @@
+"""Telemetry coverage for MCP server lifecycle spans."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+
+import pytest
+
+from basic_memory.mcp.server import lifespan, mcp
+import basic_memory.mcp.server as server_module
+
+
+@pytest.mark.asyncio
+async def test_mcp_lifespan_wraps_startup_and_shutdown(config_manager) -> None:
+    operations: list[tuple[str, dict]] = []
+
+    @contextmanager
+    def fake_operation(name: str, **attrs):
+        operations.append((name, attrs))
+        yield
+
+    original_operation = server_module.telemetry.operation
+    server_module.telemetry.operation = fake_operation
+    try:
+        async with lifespan(mcp):
+            pass
+    finally:
+        server_module.telemetry.operation = original_operation
+
+    assert [name for name, _ in operations] == [
+        "mcp.lifecycle.startup",
+        "mcp.lifecycle.shutdown",
+    ]

tests/mcp/test_tool_delete_note.py

@@ -1,6 +1,12 @@
 """Tests for delete_note MCP tool."""
 
-from basic_memory.mcp.tools.delete_note import _format_delete_error_response
+from unittest.mock import patch
+
+import pytest
+
+from basic_memory.mcp.tools.delete_note import delete_note, _format_delete_error_response
+from basic_memory.mcp.tools.read_note import read_note
+from basic_memory.mcp.tools.write_note import write_note
 
 
 class TestDeleteNoteErrorFormatting:
@@ -94,5 +100,78 @@ class TestDeleteNoteErrorFormatting:
         assert "folder/note-title" in result  # Permalink format
 
 
-# Integration tests removed to focus on error formatting coverage
-# The error formatting tests above provide the necessary coverage for MCP tool error messaging
+@pytest.mark.asyncio
+async def test_delete_note_rejects_fuzzy_match(client, test_project):
+    """delete_note must reject nonexistent identifiers, not fuzzy-match to a similar note."""
+    await write_note(
+        project=test_project.name,
+        title="Delete Target Note",
+        directory="test",
+        content="# Delete Target Note\nShould not be deleted.",
+    )
+
+    # Attempt to delete a nonexistent note — should return False, not silently delete the existing note
+    result = await delete_note(
+        project=test_project.name,
+        identifier="Delete Target NONEXISTENT",
+    )
+
+    # Should indicate not found (False or error string)
+    assert result is False or (isinstance(result, str) and "not found" in result.lower())
+
+    # Verify the existing note was NOT deleted
+    content = await read_note("Delete Target Note", project=test_project.name)
+    assert "Should not be deleted" in content
+
+
+@pytest.mark.asyncio
+async def test_delete_note_detects_project_from_memory_url(client, test_project):
+    """delete_note should detect project from memory:// URL prefix when project=None."""
+    # Create a note to delete
+    await write_note(
+        project=test_project.name,
+        title="Delete URL Note",
+        directory="test",
+        content="# Delete URL Note\nContent to delete.",
+    )
+
+    # Delete using memory:// URL with project=None — should auto-detect project
+    # The note may or may not be found (depends on URL resolution), but the key
+    # assertion is that routing goes to the correct project
+    result = await delete_note(
+        identifier=f"memory://{test_project.name}/test/delete-url-note",
+        project=None,
+    )
+
+    # Result is True (deleted) or False (not found by that URL) — either is acceptable.
+    # The important thing is it didn't error and routed to the correct project.
+    assert isinstance(result, bool)
+
+
+@pytest.mark.asyncio
+async def test_delete_note_skips_detection_for_plain_path(client, test_project):
+    """delete_note should NOT call detect_project_from_url_prefix for plain path identifiers.
+
+    A plain path like 'research/note' should not be misrouted to a project
+    named 'research' — the 'research' segment is a directory, not a project.
+    """
+    with patch("basic_memory.mcp.tools.delete_note.detect_project_from_url_prefix") as mock_detect:
+        # Use a plain path (no memory:// prefix) — detection should not be called
+        await delete_note(
+            identifier="test/nonexistent-note",
+            project=None,
+        )
+
+        mock_detect.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_delete_note_skips_detection_when_project_provided(client, test_project):
+    """delete_note should skip URL detection when project is explicitly provided."""
+    with patch("basic_memory.mcp.tools.delete_note.detect_project_from_url_prefix") as mock_detect:
+        await delete_note(
+            identifier=f"memory://{test_project.name}/test/some-note",
+            project=test_project.name,
+        )
+
+        mock_detect.assert_not_called()

tests/mcp/test_tool_edit_note.py

@@ -1,8 +1,11 @@
 """Tests for the edit_note MCP tool."""
 
+from unittest.mock import patch
+
 import pytest
 
 from basic_memory.mcp.tools.edit_note import edit_note
+from basic_memory.mcp.tools.read_note import read_note
 from basic_memory.mcp.tools.write_note import write_note
 
 
@@ -320,7 +323,7 @@ async def test_edit_note_replace_section_missing_section(client, test_project):
             content="new content",
         )
 
-    assert "section parameter is required for replace_section operation" in str(exc_info.value)
+    assert "section parameter is required for section-based operations" in str(exc_info.value)
 
 
 @pytest.mark.asyncio
@@ -611,3 +614,218 @@ async def test_edit_note_preserves_permalink_when_frontmatter_missing(client, te
     assert f"permalink: {test_project.name}/test/test-note" in second_result
     assert f"[Session: Using project '{test_project.name}']" in second_result
     # The edit should succeed without validation errors
+
+
+@pytest.mark.asyncio
+async def test_edit_note_find_replace_rejects_fuzzy_match(client, test_project):
+    """find_replace must reject nonexistent identifiers, not fuzzy-match to a similar note."""
+    # Create two notes that could be fuzzy-matched
+    await write_note(
+        project=test_project.name,
+        title="Routing Test A",
+        directory="test",
+        content="# Routing Test A\nContent A.",
+    )
+    await write_note(
+        project=test_project.name,
+        title="Routing Test B",
+        directory="test",
+        content="# Routing Test B\nContent B.",
+    )
+
+    # Attempt to edit a nonexistent note — should error, not silently edit A or B
+    result = await edit_note(
+        project=test_project.name,
+        identifier="Routing Test NONEXISTENT",
+        operation="find_replace",
+        content="replaced",
+        find_text="Content",
+    )
+
+    assert isinstance(result, str)
+    assert "# Edit Failed" in result
+
+    # Verify neither A nor B was modified
+    content_a = await read_note("Routing Test A", project=test_project.name)
+    assert "Content A" in content_a
+    content_b = await read_note("Routing Test B", project=test_project.name)
+    assert "Content B" in content_b
+
+
+@pytest.mark.asyncio
+async def test_edit_note_append_autocreate_not_fuzzy_match(client, test_project):
+    """append to a nonexistent note should auto-create it, not fuzzy-match an existing note."""
+    await write_note(
+        project=test_project.name,
+        title="Existing Note Alpha",
+        directory="test",
+        content="# Existing Note Alpha\nOriginal content.",
+    )
+
+    # Append to a nonexistent note — should create a new note, not edit "Existing Note Alpha"
+    result = await edit_note(
+        project=test_project.name,
+        identifier="Existing Note ZZZZZ",
+        operation="append",
+        content="# New Note\nBrand new content.",
+    )
+
+    assert isinstance(result, str)
+    assert "Created note (append)" in result
+    assert "fileCreated: true" in result
+
+    # Verify original note was NOT modified
+    content = await read_note("Existing Note Alpha", project=test_project.name)
+    assert "Original content" in content
+    assert "Brand new content" not in content
+
+
+@pytest.mark.asyncio
+async def test_edit_note_insert_before_section_operation(client, test_project):
+    """Test inserting content before a section heading."""
+    # Create initial note with sections
+    await write_note(
+        project=test_project.name,
+        title="Insert Before Doc",
+        directory="docs",
+        content="# Doc\n\n## Overview\nOverview content.\n\n## Details\nDetail content.",
+    )
+
+    result = await edit_note(
+        project=test_project.name,
+        identifier="docs/insert-before-doc",
+        operation="insert_before_section",
+        content="--- inserted divider ---",
+        section="## Details",
+    )
+
+    assert isinstance(result, str)
+    assert "Edited note (insert_before_section)" in result
+    assert f"project: {test_project.name}" in result
+    assert "Inserted content before section '## Details'" in result
+    assert f"[Session: Using project '{test_project.name}']" in result
+
+
+@pytest.mark.asyncio
+async def test_edit_note_insert_after_section_operation(client, test_project):
+    """Test inserting content after a section heading."""
+    # Create initial note with sections
+    await write_note(
+        project=test_project.name,
+        title="Insert After Doc",
+        directory="docs",
+        content="# Doc\n\n## Overview\nOverview content.\n\n## Details\nDetail content.",
+    )
+
+    result = await edit_note(
+        project=test_project.name,
+        identifier="docs/insert-after-doc",
+        operation="insert_after_section",
+        content="Inserted after overview heading",
+        section="## Overview",
+    )
+
+    assert isinstance(result, str)
+    assert "Edited note (insert_after_section)" in result
+    assert f"project: {test_project.name}" in result
+    assert "Inserted content after section '## Overview'" in result
+    assert f"[Session: Using project '{test_project.name}']" in result
+
+
+@pytest.mark.asyncio
+async def test_edit_note_insert_before_section_missing_section(client, test_project):
+    """Test insert_before_section without section parameter raises ValueError."""
+    await write_note(
+        project=test_project.name,
+        title="Test Note",
+        directory="test",
+        content="# Test\nContent here.",
+    )
+
+    with pytest.raises(ValueError, match="section parameter is required"):
+        await edit_note(
+            project=test_project.name,
+            identifier="test/test-note",
+            operation="insert_before_section",
+            content="new content",
+        )
+
+
+@pytest.mark.asyncio
+async def test_edit_note_insert_before_section_not_found(client, test_project):
+    """Test insert_before_section when section doesn't exist returns error."""
+    await write_note(
+        project=test_project.name,
+        title="Test Note",
+        directory="test",
+        content="# Test\n\n## Existing\nContent here.",
+    )
+
+    result = await edit_note(
+        project=test_project.name,
+        identifier="test/test-note",
+        operation="insert_before_section",
+        content="new content",
+        section="## Nonexistent",
+    )
+
+    assert isinstance(result, str)
+    assert "# Edit Failed" in result
+
+
+@pytest.mark.asyncio
+async def test_edit_note_detects_project_from_memory_url(client, test_project):
+    """edit_note should detect project from memory:// URL prefix when project=None."""
+    # Create a note first
+    await write_note(
+        project=test_project.name,
+        title="URL Detection Note",
+        directory="test",
+        content="# URL Detection Note\nOriginal content.",
+    )
+
+    # Edit using memory:// URL with project=None — should auto-detect project
+    # The memory URL uses the permalink (which includes project prefix)
+    result = await edit_note(
+        identifier=f"memory://{test_project.name}/test/url-detection-note",
+        operation="append",
+        content="\nAppended via memory URL.",
+        project=None,
+    )
+
+    assert isinstance(result, str)
+    # Should route to the correct project and succeed (either edit or create)
+    assert f"project: {test_project.name}" in result
+
+
+@pytest.mark.asyncio
+async def test_edit_note_skips_detection_for_plain_path(client, test_project):
+    """edit_note should NOT call detect_project_from_url_prefix for plain path identifiers.
+
+    A plain path like 'research/note' should not be misrouted to a project
+    named 'research' — the 'research' segment is a directory, not a project.
+    """
+    with patch("basic_memory.mcp.tools.edit_note.detect_project_from_url_prefix") as mock_detect:
+        # Use a plain path (no memory:// prefix) — detection should not be called
+        await edit_note(
+            identifier="test/some-note",
+            operation="append",
+            content="content",
+            project=None,
+        )
+
+        mock_detect.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_edit_note_skips_detection_when_project_provided(client, test_project):
+    """edit_note should skip URL detection when project is explicitly provided."""
+    with patch("basic_memory.mcp.tools.edit_note.detect_project_from_url_prefix") as mock_detect:
+        await edit_note(
+            identifier=f"memory://{test_project.name}/test/some-note",
+            operation="append",
+            content="content",
+            project=test_project.name,
+        )
+
+        mock_detect.assert_not_called()

tests/mcp/test_tool_move_note.py

@@ -590,6 +590,31 @@ async def test_move_note_preserves_frontmatter(app, client, test_project):
     assert "Content with custom metadata" in content
 
 
+@pytest.mark.asyncio
+async def test_move_note_rejects_fuzzy_match(client, test_project):
+    """move_note must reject nonexistent identifiers, not fuzzy-match to a similar note."""
+    await write_note(
+        project=test_project.name,
+        title="Move Target Note",
+        directory="source",
+        content="# Move Target Note\nShould not be moved.",
+    )
+
+    # Attempt to move a nonexistent note — should error, not silently move the existing note
+    result = await move_note(
+        project=test_project.name,
+        identifier="Move Target NONEXISTENT",
+        destination_path="target/Moved.md",
+    )
+
+    assert isinstance(result, str)
+    assert "# Move Failed" in result
+
+    # Verify the existing note was NOT moved
+    content = await read_note("Move Target Note", project=test_project.name)
+    assert "Should not be moved" in content
+
+
 class TestMoveNoteErrorFormatting:
     """Test move note error formatting for better user experience."""
 

tests/mcp/test_tool_search.py

@@ -788,6 +788,7 @@ async def test_search_notes_defaults_to_hybrid_when_semantic_enabled(monkeypatch
     @dataclass
     class StubConfig:
         semantic_search_enabled: bool = True
+        default_search_type: str | None = None
 
     @dataclass
     class StubContainer:
@@ -849,6 +850,7 @@ async def test_search_notes_defaults_to_fts_when_semantic_disabled(monkeypatch):
     @dataclass
     class StubConfig:
         semantic_search_enabled: bool = False
+        default_search_type: str | None = None
 
     @dataclass
     class StubContainer:
@@ -909,6 +911,7 @@ async def test_search_notes_explicit_text_stays_fts_when_semantic_enabled(monkey
     @dataclass
     class StubConfig:
         semantic_search_enabled: bool = True
+        default_search_type: str | None = None
 
     @dataclass
     class StubContainer:
@@ -976,7 +979,11 @@ async def test_search_notes_defaults_to_hybrid_when_container_not_initialized(mo
         lambda: type(
             "StubConfigManager",
             (),
-            {"config": type("Cfg", (), {"semantic_search_enabled": True})()},
+            {
+                "config": type(
+                    "Cfg", (), {"semantic_search_enabled": True, "default_search_type": None}
+                )()
+            },
         )(),
     )
 
@@ -1037,7 +1044,11 @@ async def test_search_notes_defaults_to_fts_when_container_not_initialized_and_s
         lambda: type(
             "StubConfigManager",
             (),
-            {"config": type("Cfg", (), {"semantic_search_enabled": False})()},
+            {
+                "config": type(
+                    "Cfg", (), {"semantic_search_enabled": False, "default_search_type": None}
+                )()
+            },
         )(),
     )
 
@@ -1146,6 +1157,54 @@ async def test_search_notes_explicit_entity_types_overrides_default(monkeypatch)
     assert captured_payload["entity_types"] == ["observation"]
 
 
+# --- Tests for note_types case-insensitivity ------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_search_notes_note_types_lowercased(monkeypatch):
+    """note_types values are lowercased so 'Chapter' matches stored 'chapter'."""
+    import importlib
+
+    search_mod = importlib.import_module("basic_memory.mcp.tools.search")
+    clients_mod = importlib.import_module("basic_memory.mcp.clients")
+
+    class StubProject:
+        name = "test-project"
+        external_id = "test-external-id"
+
+    @asynccontextmanager
+    async def fake_get_project_client(*args, **kwargs):
+        yield (object(), StubProject())
+
+    async def fake_resolve_project_and_path(
+        client, identifier, project=None, context=None, headers=None
+    ):
+        return StubProject(), identifier, False
+
+    captured_payload: dict = {}
+
+    class MockSearchClient:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        async def search(self, payload, page, page_size):
+            captured_payload.update(payload)
+            return SearchResponse(results=[], current_page=page, page_size=page_size)
+
+    monkeypatch.setattr(search_mod, "get_project_client", fake_get_project_client)
+    monkeypatch.setattr(search_mod, "resolve_project_and_path", fake_resolve_project_and_path)
+    monkeypatch.setattr(clients_mod, "SearchClient", MockSearchClient)
+
+    await search_mod.search_notes(
+        project="test-project",
+        query="test",
+        note_types=["Chapter", "Person"],
+    )
+
+    # note_types should be lowercased
+    assert captured_payload["note_types"] == ["chapter", "person"]
+
+
 # --- Tests for tag: prefix parsing (issue #30) ---------------------------------
 
 
@@ -1519,3 +1578,54 @@ async def test_search_notes_metadata_filters_preserves_non_aliased_keys(monkeypa
 
     # "note_type" aliased to "type", "priority" passes through unchanged
     assert captured_payload["metadata_filters"] == {"type": "spec", "priority": "high"}
+
+
+def test_default_search_type_uses_config_value():
+    """_default_search_type should return config.default_search_type when set."""
+    import sys
+    from unittest.mock import MagicMock, patch
+
+    search_module = sys.modules["basic_memory.mcp.tools.search"]
+
+    mock_config = MagicMock()
+    mock_config.default_search_type = "vector"
+    mock_config.semantic_search_enabled = True
+    mock_container = MagicMock()
+    mock_container.config = mock_config
+
+    with patch.object(search_module, "get_container", return_value=mock_container):
+        assert search_module._default_search_type() == "vector"
+
+
+def test_default_search_type_falls_back_to_hybrid_when_semantic_enabled():
+    """When default_search_type is None and semantic is enabled, default to hybrid."""
+    import sys
+    from unittest.mock import MagicMock, patch
+
+    search_module = sys.modules["basic_memory.mcp.tools.search"]
+
+    mock_config = MagicMock()
+    mock_config.default_search_type = None
+    mock_config.semantic_search_enabled = True
+    mock_container = MagicMock()
+    mock_container.config = mock_config
+
+    with patch.object(search_module, "get_container", return_value=mock_container):
+        assert search_module._default_search_type() == "hybrid"
+
+
+def test_default_search_type_falls_back_to_text_when_semantic_disabled():
+    """When default_search_type is None and semantic is disabled, default to text."""
+    import sys
+    from unittest.mock import MagicMock, patch
+
+    search_module = sys.modules["basic_memory.mcp.tools.search"]
+
+    mock_config = MagicMock()
+    mock_config.default_search_type = None
+    mock_config.semantic_search_enabled = False
+    mock_container = MagicMock()
+    mock_container.config = mock_config
+
+    with patch.object(search_module, "get_container", return_value=mock_container):
+        assert search_module._default_search_type() == "text"

tests/mcp/test_tool_telemetry.py

@@ -0,0 +1,309 @@
+"""Telemetry coverage for MCP tool root spans."""
+
+from __future__ import annotations
+
+import importlib
+from contextlib import contextmanager
+
+import pytest
+
+build_context_module = importlib.import_module("basic_memory.mcp.tools.build_context")
+edit_note_module = importlib.import_module("basic_memory.mcp.tools.edit_note")
+read_note_module = importlib.import_module("basic_memory.mcp.tools.read_note")
+search_module = importlib.import_module("basic_memory.mcp.tools.search")
+write_note_module = importlib.import_module("basic_memory.mcp.tools.write_note")
+
+
+def _recording_contexts():
+    operations: list[tuple[str, dict]] = []
+    contexts: list[dict] = []
+
+    @contextmanager
+    def fake_operation(name: str, **attrs):
+        operations.append((name, attrs))
+        yield
+
+    @contextmanager
+    def fake_contextualize(**attrs):
+        contexts.append(attrs)
+        yield
+
+    return operations, contexts, fake_operation, fake_contextualize
+
+
+def _contains_context(contexts: list[dict], expected: dict) -> bool:
+    return any(expected.items() <= context.items() for context in contexts)
+
+
+@pytest.mark.asyncio
+async def test_write_note_emits_root_operation_and_project_context(
+    app, test_project, monkeypatch
+) -> None:
+    operations, contexts, fake_operation, fake_contextualize = _recording_contexts()
+    monkeypatch.setattr(write_note_module.telemetry, "operation", fake_operation)
+    monkeypatch.setattr(write_note_module.telemetry, "contextualize", fake_contextualize)
+
+    await write_note_module.write_note(
+        project=test_project.name,
+        title="Telemetry Note",
+        directory="notes",
+        content="Telemetry content",
+        output_format="json",
+    )
+
+    assert operations == [
+        (
+            "mcp.tool.write_note",
+            {
+                "entrypoint": "mcp",
+                "tool_name": "write_note",
+                "requested_project": test_project.name,
+                "workspace_id": None,
+                "note_type": "note",
+                "overwrite": False,
+                "output_format": "json",
+            },
+        )
+    ]
+    assert _contains_context(
+        contexts,
+        {
+            "project_name": test_project.name,
+            "route_mode": "local_asgi",
+        },
+    )
+    assert _contains_context(
+        contexts,
+        {
+            "project_name": test_project.name,
+            "tool_name": "write_note",
+        },
+    )
+
+
+@pytest.mark.asyncio
+async def test_read_note_emits_root_operation_and_project_context(
+    app, test_project, monkeypatch
+) -> None:
+    await write_note_module.write_note(
+        project=test_project.name,
+        title="Readable Telemetry Note",
+        directory="notes",
+        content="Readable telemetry content",
+    )
+
+    operations, contexts, fake_operation, fake_contextualize = _recording_contexts()
+    monkeypatch.setattr(read_note_module.telemetry, "operation", fake_operation)
+    monkeypatch.setattr(read_note_module.telemetry, "contextualize", fake_contextualize)
+
+    await read_note_module.read_note(
+        "notes/readable-telemetry-note",
+        project=test_project.name,
+        output_format="json",
+        include_frontmatter=True,
+    )
+
+    assert operations == [
+        (
+            "mcp.tool.read_note",
+            {
+                "entrypoint": "mcp",
+                "tool_name": "read_note",
+                "requested_project": test_project.name,
+                "workspace_id": None,
+                "output_format": "json",
+                "page": 1,
+                "page_size": 10,
+                "include_frontmatter": True,
+            },
+        )
+    ]
+    assert _contains_context(
+        contexts,
+        {
+            "project_name": test_project.name,
+            "route_mode": "local_asgi",
+        },
+    )
+    assert _contains_context(
+        contexts,
+        {
+            "project_name": test_project.name,
+            "tool_name": "read_note",
+        },
+    )
+
+
+@pytest.mark.asyncio
+async def test_search_notes_emits_root_operation_and_project_context(
+    app, test_project, monkeypatch
+) -> None:
+    await write_note_module.write_note(
+        project=test_project.name,
+        title="Searchable Telemetry Note",
+        directory="notes",
+        content="Telemetry search content",
+        tags=["telemetry"],
+    )
+
+    operations, contexts, fake_operation, fake_contextualize = _recording_contexts()
+    monkeypatch.setattr(search_module.telemetry, "operation", fake_operation)
+    monkeypatch.setattr(search_module.telemetry, "contextualize", fake_contextualize)
+
+    await search_module.search_notes(
+        project=test_project.name,
+        query="telemetry",
+        search_type="text",
+        tags=["telemetry"],
+        output_format="json",
+    )
+
+    assert operations[0] == (
+        "mcp.tool.search_notes",
+        {
+            "entrypoint": "mcp",
+            "tool_name": "search_notes",
+            "requested_project": test_project.name,
+            "workspace_id": None,
+            "search_type": "text",
+            "output_format": "json",
+            "page": 1,
+            "page_size": 10,
+            "has_query": True,
+            "note_type_filter_count": 0,
+            "entity_type_filter_count": 0,
+            "has_metadata_filters": False,
+            "has_tags_filter": True,
+            "has_status_filter": False,
+        },
+    )
+    assert ("api.request.search",) == (operations[1][0],)
+    assert _contains_context(
+        contexts,
+        {
+            "project_name": test_project.name,
+            "route_mode": "local_asgi",
+        },
+    )
+    assert _contains_context(
+        contexts,
+        {
+            "project_name": test_project.name,
+            "tool_name": "search_notes",
+        },
+    )
+
+
+@pytest.mark.asyncio
+async def test_edit_note_emits_root_operation_and_project_context(
+    app, test_project, monkeypatch
+) -> None:
+    await write_note_module.write_note(
+        project=test_project.name,
+        title="Editable Telemetry Note",
+        directory="notes",
+        content="Original telemetry content",
+    )
+
+    operations, contexts, fake_operation, fake_contextualize = _recording_contexts()
+    monkeypatch.setattr(edit_note_module.telemetry, "operation", fake_operation)
+    monkeypatch.setattr(edit_note_module.telemetry, "contextualize", fake_contextualize)
+
+    await edit_note_module.edit_note(
+        "notes/editable-telemetry-note",
+        operation="append",
+        content="\n\nAppended telemetry content",
+        project=test_project.name,
+        output_format="json",
+    )
+
+    assert operations == [
+        (
+            "mcp.tool.edit_note",
+            {
+                "entrypoint": "mcp",
+                "tool_name": "edit_note",
+                "requested_project": test_project.name,
+                "workspace_id": None,
+                "edit_operation": "append",
+                "output_format": "json",
+                "has_section": False,
+                "has_find_text": False,
+                "expected_replacements": 1,
+            },
+        )
+    ]
+    assert _contains_context(
+        contexts,
+        {
+            "project_name": test_project.name,
+            "route_mode": "local_asgi",
+        },
+    )
+    assert _contains_context(
+        contexts,
+        {
+            "project_name": test_project.name,
+            "tool_name": "edit_note",
+        },
+    )
+
+
+@pytest.mark.asyncio
+async def test_build_context_emits_root_operation_and_project_context(
+    app, test_project, monkeypatch
+) -> None:
+    await write_note_module.write_note(
+        project=test_project.name,
+        title="Context Telemetry Note",
+        directory="notes",
+        content="Context telemetry content",
+    )
+
+    operations, contexts, fake_operation, fake_contextualize = _recording_contexts()
+    monkeypatch.setattr(build_context_module.telemetry, "operation", fake_operation)
+    monkeypatch.setattr(build_context_module.telemetry, "contextualize", fake_contextualize)
+
+    await build_context_module.build_context(
+        url="memory://notes/context-telemetry-note",
+        project=test_project.name,
+        depth=2,
+        timeframe="7d",
+        page=1,
+        page_size=5,
+        max_related=3,
+        output_format="json",
+    )
+
+    assert operations == [
+        (
+            "mcp.tool.build_context",
+            {
+                "entrypoint": "mcp",
+                "tool_name": "build_context",
+                "requested_project": test_project.name,
+                "workspace_id": None,
+                "depth": 2,
+                "timeframe": "7d",
+                "page": 1,
+                "page_size": 5,
+                "max_related": 3,
+                "output_format": "json",
+                "is_memory_url": True,
+            },
+        )
+    ]
+    assert _contains_context(
+        contexts,
+        {
+            "project_name": test_project.name,
+            "route_mode": "local_asgi",
+        },
+    )
+    assert _contains_context(
+        contexts,
+        {
+            "project_name": test_project.name,
+            "tool_name": "build_context",
+        },
+    )

tests/mcp/test_tool_write_note.py

@@ -1257,6 +1257,11 @@ class TestWriteNoteOverwriteGuard:
         # Set config to allow overwrites by default
         app_config.write_note_overwrite_default = True
         config_module._CONFIG_CACHE = app_config
+        # Pin mtime+size to the on-disk file so the cache guard sees a match
+        # and keeps our injected config instead of re-reading from disk.
+        _st = config_manager.config_file.stat()
+        config_module._CONFIG_MTIME = _st.st_mtime
+        config_module._CONFIG_SIZE = _st.st_size
 
         try:
             await write_note(
@@ -1281,6 +1286,9 @@ class TestWriteNoteOverwriteGuard:
             # Restore config
             app_config.write_note_overwrite_default = False
             config_module._CONFIG_CACHE = app_config
+            _st = config_manager.config_file.stat()
+            config_module._CONFIG_MTIME = _st.st_mtime
+            config_module._CONFIG_SIZE = _st.st_size
 
     @pytest.mark.asyncio
     async def test_write_note_new_note_unaffected(self, app, test_project):

tests/repository/test_semantic_search_base.py

@@ -237,6 +237,29 @@ class TestBuildChunkRecords:
         records = self.repo._build_chunk_records(rows)
         assert any("99" in r["chunk_key"] for r in records)
 
+    def test_duplicate_rows_collapse_to_unique_chunk_keys(self):
+        rows = [
+            _make_row(
+                row_type=SearchItemType.ENTITY.value,
+                title="Spec",
+                permalink="spec",
+                content_snippet="shared content",
+                row_id=77,
+            ),
+            _make_row(
+                row_type=SearchItemType.ENTITY.value,
+                title="Spec",
+                permalink="spec",
+                content_snippet="shared content",
+                row_id=77,
+            ),
+        ]
+
+        records = self.repo._build_chunk_records(rows)
+
+        assert len(records) == 1
+        assert records[0]["chunk_key"] == "entity:77:0"
+
 
 # --- SQLite SemanticSearchDisabledError ---
 

tests/schemas/test_schemas.py

@@ -345,7 +345,7 @@ def test_edit_entity_request_find_replace_empty_find_text():
 def test_edit_entity_request_replace_section_empty_section():
     """Test that replace_section operation requires non-empty section parameter."""
     with pytest.raises(
-        ValueError, match="section parameter is required for replace_section operation"
+        ValueError, match="section parameter is required for section-based operations"
     ):
         EditEntityRequest.model_validate(
             {
@@ -356,6 +356,46 @@ def test_edit_entity_request_replace_section_empty_section():
         )
 
 
+def test_edit_entity_request_insert_before_section():
+    """Test insert_before_section is a valid operation."""
+    edit_request = EditEntityRequest.model_validate(
+        {
+            "operation": "insert_before_section",
+            "content": "content to insert",
+            "section": "## Target Section",
+        }
+    )
+    assert edit_request.operation == "insert_before_section"
+    assert edit_request.section == "## Target Section"
+
+
+def test_edit_entity_request_insert_after_section():
+    """Test insert_after_section is a valid operation."""
+    edit_request = EditEntityRequest.model_validate(
+        {
+            "operation": "insert_after_section",
+            "content": "content to insert",
+            "section": "## Target Section",
+        }
+    )
+    assert edit_request.operation == "insert_after_section"
+    assert edit_request.section == "## Target Section"
+
+
+def test_edit_entity_request_insert_before_section_empty_section():
+    """Test that insert_before_section requires non-empty section parameter."""
+    with pytest.raises(
+        ValueError, match="section parameter is required for section-based operations"
+    ):
+        EditEntityRequest.model_validate(
+            {
+                "operation": "insert_before_section",
+                "content": "content",
+                "section": "",
+            }
+        )
+
+
 # New tests for timeframe parsing functions
 class TestTimeframeParsing:
     """Test cases for parse_timeframe() and validate_timeframe() functions."""
@@ -391,7 +431,7 @@ class TestTimeframeParsing:
         result_1d = parse_timeframe("1d")
         expected_1d = now - timedelta(days=1)
         diff = abs((result_1d - expected_1d).total_seconds())
-        assert diff < 3600  # Within 1 hour tolerance (accounts for DST transitions)
+        assert diff <= 3610  # Within 1 hour tolerance + execution margin (DST transitions)
         assert result_1d.tzinfo is not None
 
         # Test yesterday - should be yesterday at same time
@@ -404,7 +444,7 @@ class TestTimeframeParsing:
         result_week = parse_timeframe("1 week ago")
         expected_week = now - timedelta(weeks=1)
         diff = abs((result_week - expected_week).total_seconds())
-        assert diff < 3600  # Within 1 hour tolerance
+        assert diff <= 3610  # Within 1 hour tolerance + execution margin (DST transitions)
         assert result_week.tzinfo is not None
 
     def test_parse_timeframe_invalid(self):

tests/services/test_entity_service.py

@@ -1402,6 +1402,267 @@ async def test_edit_entity_replace_section_strips_duplicate_header(
     assert "## Another Section" in file_content  # Other sections preserved
 
 
+# Insert before/after section tests
+@pytest.mark.asyncio
+async def test_edit_entity_insert_before_section(
+    entity_service: EntityService, file_service: FileService
+):
+    """Test inserting content before a section heading."""
+    content = dedent("""
+        # Main Title
+
+        ## Section 1
+        Section 1 content
+
+        ## Section 2
+        Section 2 content
+        """).strip()
+
+    entity = await entity_service.create_entity(
+        EntitySchema(
+            title="Insert Before Test",
+            directory="docs",
+            note_type="note",
+            content=content,
+        )
+    )
+
+    updated = await entity_service.edit_entity(
+        identifier=entity.permalink,
+        operation="insert_before_section",
+        content="Inserted before section 2",
+        section="## Section 2",
+    )
+
+    file_path = file_service.get_entity_path(updated)
+    file_content, _ = await file_service.read_file(file_path)
+    assert "Inserted before section 2" in file_content
+    assert "## Section 2" in file_content
+    assert "Section 2 content" in file_content
+    # Inserted content should appear before the section heading
+    assert file_content.index("Inserted before section 2") < file_content.index("## Section 2")
+
+
+@pytest.mark.asyncio
+async def test_edit_entity_insert_after_section(
+    entity_service: EntityService, file_service: FileService
+):
+    """Test inserting content after a section heading."""
+    content = dedent("""
+        # Main Title
+
+        ## Section 1
+        Section 1 content
+
+        ## Section 2
+        Section 2 content
+        """).strip()
+
+    entity = await entity_service.create_entity(
+        EntitySchema(
+            title="Insert After Test",
+            directory="docs",
+            note_type="note",
+            content=content,
+        )
+    )
+
+    updated = await entity_service.edit_entity(
+        identifier=entity.permalink,
+        operation="insert_after_section",
+        content="Inserted after section 1 heading",
+        section="## Section 1",
+    )
+
+    file_path = file_service.get_entity_path(updated)
+    file_content, _ = await file_service.read_file(file_path)
+    assert "Inserted after section 1 heading" in file_content
+    assert "## Section 1" in file_content
+    assert "Section 1 content" in file_content
+    # Inserted content should appear after the heading but content is also preserved
+    assert file_content.index("## Section 1") < file_content.index(
+        "Inserted after section 1 heading"
+    )
+
+
+@pytest.mark.asyncio
+async def test_edit_entity_insert_before_section_not_found(entity_service: EntityService):
+    """Test insert_before_section raises ValueError when section not found."""
+    entity = await entity_service.create_entity(
+        EntitySchema(
+            title="Test Note",
+            directory="test",
+            note_type="note",
+            content="# Main Title\n\nSome content",
+        )
+    )
+
+    with pytest.raises(ValueError, match="Section '## Missing' not found"):
+        await entity_service.edit_entity(
+            identifier=entity.permalink,
+            operation="insert_before_section",
+            content="new content",
+            section="## Missing",
+        )
+
+
+@pytest.mark.asyncio
+async def test_edit_entity_insert_after_section_not_found(entity_service: EntityService):
+    """Test insert_after_section raises ValueError when section not found."""
+    entity = await entity_service.create_entity(
+        EntitySchema(
+            title="Test Note",
+            directory="test",
+            note_type="note",
+            content="# Main Title\n\nSome content",
+        )
+    )
+
+    with pytest.raises(ValueError, match="Section '## Missing' not found"):
+        await entity_service.edit_entity(
+            identifier=entity.permalink,
+            operation="insert_after_section",
+            content="new content",
+            section="## Missing",
+        )
+
+
+@pytest.mark.asyncio
+async def test_edit_entity_insert_before_section_multiple_sections_error(
+    entity_service: EntityService,
+):
+    """Test insert_before_section raises ValueError with duplicate sections."""
+    entity = await entity_service.create_entity(
+        EntitySchema(
+            title="Test Note",
+            directory="test",
+            note_type="note",
+            content="# Title\n\n## Dup\nFirst\n\n## Dup\nSecond",
+        )
+    )
+
+    with pytest.raises(ValueError, match="Multiple sections found"):
+        await entity_service.edit_entity(
+            identifier=entity.permalink,
+            operation="insert_before_section",
+            content="new content",
+            section="## Dup",
+        )
+
+
+@pytest.mark.asyncio
+async def test_edit_entity_insert_before_section_missing_section_param(
+    entity_service: EntityService,
+):
+    """Test insert_before_section raises ValueError when section param is missing."""
+    entity = await entity_service.create_entity(
+        EntitySchema(
+            title="Test Note",
+            directory="test",
+            note_type="note",
+            content="# Title\n\nContent",
+        )
+    )
+
+    with pytest.raises(ValueError, match="section is required"):
+        await entity_service.edit_entity(
+            identifier=entity.permalink,
+            operation="insert_before_section",
+            content="new content",
+        )
+
+
+@pytest.mark.asyncio
+async def test_edit_entity_insert_before_section_empty_section(entity_service: EntityService):
+    """Test insert_before_section raises ValueError when section is empty/whitespace."""
+    entity = await entity_service.create_entity(
+        EntitySchema(
+            title="Test Note",
+            directory="test",
+            note_type="note",
+            content="# Title\n\nContent",
+        )
+    )
+
+    with pytest.raises(ValueError, match="section cannot be empty"):
+        await entity_service.edit_entity(
+            identifier=entity.permalink,
+            operation="insert_before_section",
+            content="new content",
+            section="   ",
+        )
+
+
+@pytest.mark.asyncio
+async def test_edit_entity_insert_after_section_at_end_of_document(
+    entity_service: EntityService, file_service: FileService
+):
+    """Test inserting after the last section in a document."""
+    content = dedent("""
+        # Main Title
+
+        ## Only Section
+        Some content here
+        """).strip()
+
+    entity = await entity_service.create_entity(
+        EntitySchema(
+            title="Insert End Test",
+            directory="docs",
+            note_type="note",
+            content=content,
+        )
+    )
+
+    updated = await entity_service.edit_entity(
+        identifier=entity.permalink,
+        operation="insert_after_section",
+        content="Inserted after the last section heading",
+        section="## Only Section",
+    )
+
+    file_path = file_service.get_entity_path(updated)
+    file_content, _ = await file_service.read_file(file_path)
+    assert "Inserted after the last section heading" in file_content
+    assert "## Only Section" in file_content
+    assert "Some content here" in file_content
+
+
+@pytest.mark.asyncio
+async def test_edit_entity_insert_after_section_preserves_paragraph_separation(
+    entity_service: EntityService, file_service: FileService
+):
+    """Test that insert_after_section adds blank line so inserted text doesn't merge
+    with existing section content into a single markdown paragraph."""
+    content = dedent("""
+        # Main Title
+
+        ## Section
+        Existing paragraph text
+        """).strip()
+
+    entity = await entity_service.create_entity(
+        EntitySchema(
+            title="Paragraph Sep Test",
+            directory="docs",
+            note_type="note",
+            content=content,
+        )
+    )
+
+    updated = await entity_service.edit_entity(
+        identifier=entity.permalink,
+        operation="insert_after_section",
+        content="Inserted line",
+        section="## Section",
+    )
+
+    file_path = file_service.get_entity_path(updated)
+    file_content, _ = await file_service.read_file(file_path)
+    # The inserted line and existing content should be separated by a blank line
+    assert "Inserted line\n\nExisting paragraph text" in file_content
+
+
 # Move entity tests
 @pytest.mark.asyncio
 async def test_move_entity_success(

tests/services/test_initialization.py

@@ -200,10 +200,10 @@ async def test_initialize_app_no_precedence_warning_when_not_conflicting(
 
 
 @pytest.mark.asyncio
-async def test_run_migrations_triggers_embedding_backfill_on_new_revision(
+async def test_run_migrations_triggers_embedding_backfill_when_entities_exist_but_no_embeddings(
     monkeypatch, app_config: BasicMemoryConfig
 ):
-    """When the trigger revision is newly applied, run automatic embedding backfill once."""
+    """run_migrations checks for missing embeddings (actual backfill runs in background from MCP)."""
 
     class StubSearchRepository:
         def __init__(self, *args, **kwargs):
@@ -224,29 +224,24 @@ async def test_run_migrations_triggers_embedding_backfill_on_new_revision(
         monkeypatch.setattr("basic_memory.db.SQLiteSearchRepository", StubSearchRepository)
         monkeypatch.setattr("basic_memory.db.PostgresSearchRepository", StubSearchRepository)
 
-        load_revisions_mock = AsyncMock(
-            side_effect=[
-                set(),
-                {db.SEMANTIC_EMBEDDING_BACKFILL_REVISION},
-            ]
+        needs_backfill_mock = AsyncMock(return_value=True)
+        monkeypatch.setattr(
+            "basic_memory.db._needs_semantic_embedding_backfill", needs_backfill_mock
         )
-        backfill_mock = AsyncMock()
-        monkeypatch.setattr("basic_memory.db._load_applied_alembic_revisions", load_revisions_mock)
-        monkeypatch.setattr("basic_memory.db._run_semantic_embedding_backfill", backfill_mock)
 
         await db.run_migrations(app_config)
 
-        assert load_revisions_mock.await_count == 2
-        backfill_mock.assert_awaited_once_with(app_config, session_marker)
+        # Verifies the check runs — backfill itself is launched by MCP lifespan
+        needs_backfill_mock.assert_awaited_once_with(app_config, session_marker)
     finally:
         db._session_maker = original_session_maker  # pyright: ignore [reportPrivateUsage]
 
 
 @pytest.mark.asyncio
-async def test_run_migrations_skips_embedding_backfill_when_revision_already_applied(
+async def test_run_migrations_skips_embedding_backfill_when_embeddings_already_exist(
     monkeypatch, app_config: BasicMemoryConfig
 ):
-    """If the trigger revision was already present before upgrade, skip backfill."""
+    """When embeddings already exist, no backfill is needed."""
 
     class StubSearchRepository:
         def __init__(self, *args, **kwargs):
@@ -267,20 +262,14 @@ async def test_run_migrations_skips_embedding_backfill_when_revision_already_app
         monkeypatch.setattr("basic_memory.db.SQLiteSearchRepository", StubSearchRepository)
         monkeypatch.setattr("basic_memory.db.PostgresSearchRepository", StubSearchRepository)
 
-        load_revisions_mock = AsyncMock(
-            side_effect=[
-                {db.SEMANTIC_EMBEDDING_BACKFILL_REVISION},
-                {db.SEMANTIC_EMBEDDING_BACKFILL_REVISION},
-            ]
+        needs_backfill_mock = AsyncMock(return_value=False)
+        monkeypatch.setattr(
+            "basic_memory.db._needs_semantic_embedding_backfill", needs_backfill_mock
         )
-        backfill_mock = AsyncMock()
-        monkeypatch.setattr("basic_memory.db._load_applied_alembic_revisions", load_revisions_mock)
-        monkeypatch.setattr("basic_memory.db._run_semantic_embedding_backfill", backfill_mock)
 
         await db.run_migrations(app_config)
 
-        assert load_revisions_mock.await_count == 2
-        assert backfill_mock.await_count == 0
+        needs_backfill_mock.assert_awaited_once_with(app_config, session_marker)
     finally:
         db._session_maker = original_session_maker  # pyright: ignore [reportPrivateUsage]
 
@@ -378,3 +367,58 @@ async def test_semantic_embedding_backfill_skips_when_semantic_disabled(
     app_config.semantic_search_enabled = False
     await db._run_semantic_embedding_backfill(app_config, session_maker)  # pyright: ignore [reportPrivateUsage]
     assert called is False
+
+
+@pytest.mark.asyncio
+async def test_needs_semantic_embedding_backfill_true_when_entities_exist_no_embeddings(
+    app_config: BasicMemoryConfig,
+    session_maker,
+    test_project,
+):
+    """Should return True when entities exist but vector chunks table is empty."""
+    from basic_memory.repository.entity_repository import EntityRepository
+
+    entity_repository = EntityRepository(session_maker, project_id=test_project.id)
+    await entity_repository.create(
+        {
+            "title": "Test Entity",
+            "note_type": "note",
+            "entity_metadata": {},
+            "content_type": "text/markdown",
+            "file_path": "test/backfill-check.md",
+            "permalink": "test/backfill-check",
+            "project_id": test_project.id,
+            "created_at": datetime.now(),
+            "updated_at": datetime.now(),
+        }
+    )
+
+    # Clear any embeddings left by other tests in the shared DB
+    async with db.scoped_session(session_maker) as session:
+        await session.execute(db.text("DELETE FROM search_vector_chunks"))
+
+    app_config.semantic_search_enabled = True
+    result = await db._needs_semantic_embedding_backfill(app_config, session_maker)  # pyright: ignore [reportPrivateUsage]
+    assert result is True
+
+
+@pytest.mark.asyncio
+async def test_needs_semantic_embedding_backfill_false_when_no_entities(
+    app_config: BasicMemoryConfig,
+    session_maker,
+):
+    """Should return False when no entities exist (nothing to backfill)."""
+    app_config.semantic_search_enabled = True
+    result = await db._needs_semantic_embedding_backfill(app_config, session_maker)  # pyright: ignore [reportPrivateUsage]
+    assert result is False
+
+
+@pytest.mark.asyncio
+async def test_needs_semantic_embedding_backfill_false_when_semantic_disabled(
+    app_config: BasicMemoryConfig,
+    session_maker,
+):
+    """Should return False when semantic search is disabled."""
+    app_config.semantic_search_enabled = False
+    result = await db._needs_semantic_embedding_backfill(app_config, session_maker)  # pyright: ignore [reportPrivateUsage]
+    assert result is False

tests/services/test_project_service.py

@@ -778,6 +778,8 @@ async def test_add_project_with_project_root_sanitizes_paths(
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         test_cases = [
             # (project_name, user_path, expected_sanitized_name)
@@ -845,6 +847,8 @@ async def test_add_project_with_project_root_rejects_escape_attempts(
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         # All of these should succeed by being sanitized to paths under project_root
         # The sanitization removes dangerous patterns, so they don't escape
@@ -931,6 +935,8 @@ async def test_add_project_with_project_root_normalizes_case(
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         test_cases = [
             # (input_path, expected_normalized_path)
@@ -985,6 +991,8 @@ async def test_add_project_with_project_root_detects_case_collisions(
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         # First, create a project with lowercase path
         first_project = "documents-project"
@@ -1159,6 +1167,8 @@ async def test_add_project_nested_validation_with_project_root(
         from basic_memory import config as config_module
 
         config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
 
         parent_project_name = f"cloud-parent-{os.urandom(4).hex()}"
         child_project_name = f"cloud-child-{os.urandom(4).hex()}"

tests/services/test_project_service_embedding_status.py

@@ -5,6 +5,7 @@ from unittest.mock import patch
 
 import pytest
 from sqlalchemy import text
+from sqlalchemy.exc import OperationalError as SAOperationalError
 
 from basic_memory.schemas.project_info import EmbeddingStatus
 from basic_memory.services.project_service import ProjectService
@@ -142,6 +143,46 @@ async def test_embedding_status_orphaned_chunks(
     assert "orphaned chunks" in (status.reindex_reason or "")
 
 
+@pytest.mark.asyncio
+async def test_embedding_status_handles_sqlite_vec_unavailable(
+    project_service: ProjectService, test_graph, test_project
+):
+    """Unreadable vec0 tables should degrade to unavailable status instead of crashing."""
+    # Trigger: Postgres test matrix executes the same unit suite.
+    # Why: sqlite-vec loading failures are specific to SQLite virtual tables, not Postgres joins.
+    # Outcome: keep the regression focused on the backend that can actually hit this path.
+    if _is_postgres():
+        pytest.skip("sqlite-vec unavailable handling is SQLite-specific.")
+
+    original_execute_query = project_service.repository.execute_query
+
+    async def _execute_query_with_vec0_failure(query, params):
+        query_text = str(query)
+        if "JOIN search_vector_embeddings" in query_text:
+            raise SAOperationalError(query_text, params, Exception("no such module: vec0"))
+        return await original_execute_query(query, params)
+
+    with patch.object(
+        type(project_service),
+        "config_manager",
+        new_callable=lambda: property(
+            lambda self: _config_manager_with(semantic_search_enabled=True)
+        ),
+    ):
+        with patch.object(
+            project_service.repository,
+            "execute_query",
+            side_effect=_execute_query_with_vec0_failure,
+        ):
+            status = await project_service.get_embedding_status(test_project.id)
+
+    assert status.semantic_search_enabled is True
+    assert status.total_indexed_entities > 0
+    assert status.vector_tables_exist is False
+    assert status.reindex_recommended is True
+    assert "sqlite-vec is unavailable" in (status.reindex_reason or "")
+
+
 @pytest.mark.asyncio
 async def test_embedding_status_healthy(project_service: ProjectService, test_graph, test_project):
     """When all entities have embeddings, no reindex recommended."""
@@ -210,6 +251,55 @@ async def test_embedding_status_healthy(project_service: ProjectService, test_gr
     assert status.reindex_reason is None
 
 
+@pytest.mark.asyncio
+async def test_embedding_status_excludes_stale_entity_ids(
+    project_service: ProjectService, test_graph, test_project
+):
+    """Stale rows in search_index for deleted entities should not inflate counts.
+
+    Regression test for #670: after reindex, project info reported missing embeddings
+    because stale entity_ids in search_index/search_vector_chunks inflated total_indexed_entities.
+    """
+    # Insert a stale search_index row for an entity_id that doesn't exist in the entity table.
+    # Include 'id' column — required NOT NULL on Postgres (regular table),
+    # ignored on SQLite (FTS5 virtual table where id is UNINDEXED).
+    stale_entity_id = 999999
+    await project_service.repository.execute_query(
+        text(
+            "INSERT INTO search_index "
+            "(id, entity_id, project_id, type, title, permalink, content_stems, "
+            "content_snippet, file_path, metadata) "
+            "VALUES (:id, :eid, :pid, 'entity', 'Stale Note', 'stale-note', "
+            "'stale content', 'stale snippet', 'stale.md', '{}')"
+        ),
+        {"id": stale_entity_id, "eid": stale_entity_id, "pid": test_project.id},
+    )
+
+    with patch.object(
+        type(project_service),
+        "config_manager",
+        new_callable=lambda: property(
+            lambda self: _config_manager_with(semantic_search_enabled=True)
+        ),
+    ):
+        status = await project_service.get_embedding_status(test_project.id)
+
+    # The stale entity_id should NOT be counted in total_indexed_entities.
+    # Count real entities that have search_index rows (the stale one should be excluded).
+    real_indexed_result = await project_service.repository.execute_query(
+        text(
+            "SELECT COUNT(DISTINCT si.entity_id) FROM search_index si "
+            "JOIN entity e ON e.id = si.entity_id "
+            "WHERE si.project_id = :pid"
+        ),
+        {"pid": test_project.id},
+    )
+    real_indexed_count = real_indexed_result.scalar() or 0
+
+    # Exact match — stale entity_id must not inflate the count
+    assert status.total_indexed_entities == real_indexed_count
+
+
 @pytest.mark.asyncio
 async def test_get_project_info_includes_embedding_status(
     project_service: ProjectService, test_graph, test_project

tests/services/test_search_service_telemetry.py

@@ -0,0 +1,73 @@
+"""Telemetry coverage for search execution phases."""
+
+from __future__ import annotations
+
+import importlib
+from contextlib import contextmanager
+
+import pytest
+
+from basic_memory.schemas.search import SearchQuery
+
+search_service_module = importlib.import_module("basic_memory.services.search_service")
+
+
+def _capture_spans():
+    spans: list[tuple[str, dict]] = []
+
+    @contextmanager
+    def fake_span(name: str, **attrs):
+        spans.append((name, attrs))
+        yield
+
+    return spans, fake_span
+
+
+@pytest.mark.asyncio
+async def test_search_service_wraps_repository_search(search_service, monkeypatch) -> None:
+    spans, fake_span = _capture_spans()
+    monkeypatch.setattr(search_service_module.telemetry, "span", fake_span)
+
+    await search_service.search(SearchQuery(text="Root Entity"))
+
+    assert spans[0] == (
+        "search.execute",
+        {
+            "retrieval_mode": "fts",
+            "has_text_query": True,
+            "has_title_query": False,
+            "has_permalink_query": False,
+            "has_metadata_filters": False,
+            "limit": 10,
+            "offset": 0,
+        },
+    )
+
+
+@pytest.mark.asyncio
+async def test_search_service_emits_relaxed_retry_span(search_service, monkeypatch) -> None:
+    spans, fake_span = _capture_spans()
+    calls: list[dict] = []
+
+    async def fake_repository_search(**kwargs):
+        calls.append(kwargs)
+        return []
+
+    monkeypatch.setattr(search_service_module.telemetry, "span", fake_span)
+    monkeypatch.setattr(search_service.repository, "search", fake_repository_search)
+
+    await search_service.search(SearchQuery(text="who are our main competitors and partners"))
+
+    assert [name for name, _ in spans] == ["search.execute", "search.relaxed_fts_retry"]
+    assert spans[1] == (
+        "search.relaxed_fts_retry",
+        {
+            "retrieval_mode": "fts",
+            "token_count": 7,
+            "limit": 10,
+            "offset": 0,
+        },
+    )
+    assert len(calls) == 2
+    assert calls[0]["search_text"] == "who are our main competitors and partners"
+    assert calls[1]["search_text"] == "main OR competitors OR partners"

tests/sync/test_sync_service_telemetry.py

@@ -0,0 +1,170 @@
+"""Telemetry coverage for sync phase spans."""
+
+from __future__ import annotations
+
+import importlib
+from contextlib import contextmanager
+from types import SimpleNamespace
+
+import pytest
+
+from basic_memory.sync.sync_service import SyncReport
+
+sync_service_module = importlib.import_module("basic_memory.sync.sync_service")
+
+
+def _capture_sync_telemetry():
+    operations: list[tuple[str, dict]] = []
+    spans: list[tuple[str, dict]] = []
+
+    @contextmanager
+    def fake_operation(name: str, **attrs):
+        operations.append((name, attrs))
+        yield
+
+    @contextmanager
+    def fake_span(name: str, **attrs):
+        spans.append((name, attrs))
+        yield
+
+    return operations, spans, fake_operation, fake_span
+
+
+@pytest.mark.asyncio
+async def test_sync_emits_phase_spans(sync_service, project_config, monkeypatch) -> None:
+    operations, spans, fake_operation, fake_span = _capture_sync_telemetry()
+    report = SyncReport(
+        new={"new.md"},
+        modified={"modified.md"},
+        deleted={"deleted.md"},
+        moves={"old.md": "moved.md"},
+    )
+
+    async def fake_scan(directory, force_full=False):
+        return report
+
+    async def fake_handle_move(old_path, new_path):
+        return None
+
+    async def fake_handle_delete(path):
+        return None
+
+    async def fake_sync_file(path, new=True):
+        return None, None
+
+    async def fake_should_skip_file(path):
+        return False
+
+    async def fake_resolve_relations(entity_id=None):
+        return None
+
+    async def fake_quick_count_files(directory):
+        return 3
+
+    async def fake_find_by_id(project_id):
+        return SimpleNamespace(id=project_id)
+
+    async def fake_update(project_id, values):
+        return None
+
+    monkeypatch.setattr(sync_service_module.telemetry, "operation", fake_operation)
+    monkeypatch.setattr(sync_service_module.telemetry, "span", fake_span)
+    monkeypatch.setattr(sync_service, "scan", fake_scan)
+    monkeypatch.setattr(sync_service, "handle_move", fake_handle_move)
+    monkeypatch.setattr(sync_service, "handle_delete", fake_handle_delete)
+    monkeypatch.setattr(sync_service, "sync_file", fake_sync_file)
+    monkeypatch.setattr(sync_service, "_should_skip_file", fake_should_skip_file)
+    monkeypatch.setattr(sync_service, "resolve_relations", fake_resolve_relations)
+    monkeypatch.setattr(sync_service, "_quick_count_files", fake_quick_count_files)
+    monkeypatch.setattr(sync_service.project_repository, "find_by_id", fake_find_by_id)
+    monkeypatch.setattr(sync_service.project_repository, "update", fake_update)
+    sync_service.app_config.semantic_search_enabled = False
+
+    result = await sync_service.sync(
+        project_config.home,
+        project_name=project_config.name,
+        force_full=True,
+    )
+
+    assert result is report
+    assert operations == [
+        (
+            "sync.project.run",
+            {"project_name": project_config.name, "force_full": True},
+        )
+    ]
+    assert [name for name, _ in spans] == [
+        "sync.project.scan",
+        "sync.project.apply_changes",
+        "sync.project.resolve_relations",
+        "sync.project.update_watermark",
+    ]
+
+
+@pytest.mark.asyncio
+async def test_sync_file_emits_failure_span(sync_service, monkeypatch) -> None:
+    _, spans, _, fake_span = _capture_sync_telemetry()
+    recorded_failures: list[tuple[str, str]] = []
+
+    async def fake_record_failure(path, error):
+        recorded_failures.append((path, error))
+
+    async def fail_sync_markdown_file(path, new=True):
+        raise ValueError("boom")
+
+    monkeypatch.setattr(sync_service_module.telemetry, "span", fake_span)
+    monkeypatch.setattr(sync_service, "_should_skip_file", lambda path: _false_async())
+    monkeypatch.setattr(sync_service.file_service, "is_markdown", lambda path: True)
+    monkeypatch.setattr(sync_service, "sync_markdown_file", fail_sync_markdown_file)
+    monkeypatch.setattr(sync_service, "_record_failure", fake_record_failure)
+
+    result = await sync_service.sync_file("notes/broken.md", new=True)
+
+    assert result == (None, None)
+    assert spans == [
+        (
+            "sync.file.failure",
+            {
+                "failure_type": "ValueError",
+                "path": "notes/broken.md",
+                "file_kind": "markdown",
+                "is_new": True,
+                "is_fatal": False,
+            },
+        )
+    ]
+    assert recorded_failures == [("notes/broken.md", "boom")]
+
+
+@pytest.mark.asyncio
+async def test_sync_file_logs_slow_operation(sync_service, monkeypatch) -> None:
+    warning_messages: list[str] = []
+
+    async def fake_sync_regular_file(path, new=True):
+        return SimpleNamespace(id=1), "deadbeef"
+
+    times = iter([10.0, 10.8])
+
+    monkeypatch.setattr(sync_service, "_should_skip_file", lambda path: _false_async())
+    monkeypatch.setattr(sync_service.file_service, "is_markdown", lambda path: False)
+    monkeypatch.setattr(sync_service, "sync_regular_file", fake_sync_regular_file)
+    monkeypatch.setattr(sync_service.search_service, "index_entity", _none_async)
+    monkeypatch.setattr(sync_service, "_clear_failure", lambda path: None)
+    monkeypatch.setattr(sync_service_module.time, "time", lambda: next(times))
+    monkeypatch.setattr(sync_service_module.logger, "warning", warning_messages.append)
+
+    entity, checksum = await sync_service.sync_file("assets/large.bin", new=False)
+
+    assert entity.id == 1
+    assert checksum == "deadbeef"
+    assert warning_messages == [
+        "Slow file sync detected: path=assets/large.bin, file_kind=regular, duration_ms=800"
+    ]
+
+
+async def _false_async() -> bool:
+    return False
+
+
+async def _none_async(*args, **kwargs) -> None:
+    return None

tests/test_coerce.py

@@ -0,0 +1,57 @@
+"""Tests for coerce_list and coerce_dict utility functions.
+
+These must fail until the helpers are implemented in utils.py.
+"""
+
+from basic_memory.utils import coerce_list, coerce_dict
+
+
+class TestCoerceList:
+    """Tests for coerce_list."""
+
+    def test_none_passthrough(self):
+        assert coerce_list(None) is None
+
+    def test_native_list_passthrough(self):
+        assert coerce_list(["a", "b"]) == ["a", "b"]
+
+    def test_json_array_string(self):
+        assert coerce_list('["entity", "observation"]') == ["entity", "observation"]
+
+    def test_single_string_wrapped(self):
+        assert coerce_list("entity") == ["entity"]
+
+    def test_non_json_string_wrapped(self):
+        assert coerce_list("not-json") == ["not-json"]
+
+    def test_json_object_string_wrapped(self):
+        """A JSON object string is not a list, so wrap it."""
+        assert coerce_list('{"key": "val"}') == ['{"key": "val"}']
+
+    def test_int_passthrough(self):
+        """Non-string, non-None values pass through unchanged."""
+        assert coerce_list(42) == 42
+
+
+class TestCoerceDict:
+    """Tests for coerce_dict."""
+
+    def test_none_passthrough(self):
+        assert coerce_dict(None) is None
+
+    def test_native_dict_passthrough(self):
+        assert coerce_dict({"k": "v"}) == {"k": "v"}
+
+    def test_json_object_string(self):
+        assert coerce_dict('{"status": "draft"}') == {"status": "draft"}
+
+    def test_non_json_string_passthrough(self):
+        """Non-parseable strings pass through (Pydantic will reject them)."""
+        assert coerce_dict("not-json") == "not-json"
+
+    def test_json_array_string_passthrough(self):
+        """A JSON array string is not a dict, so pass through."""
+        assert coerce_dict('["a", "b"]') == '["a", "b"]'
+
+    def test_int_passthrough(self):
+        assert coerce_dict(42) == 42

tests/test_config.py

@@ -213,6 +213,8 @@ class TestBasicMemoryConfig:
         }
         config_manager.config_file.write_text(json.dumps(config_data, indent=2))
         basic_memory.config._CONFIG_CACHE = None
+        basic_memory.config._CONFIG_MTIME = None
+        basic_memory.config._CONFIG_SIZE = None
 
         loaded = config_manager.load_config()
         assert loaded.default_project == "research"
@@ -238,6 +240,8 @@ class TestBasicMemoryConfig:
         }
         config_manager.config_file.write_text(json.dumps(config_data, indent=2))
         basic_memory.config._CONFIG_CACHE = None
+        basic_memory.config._CONFIG_MTIME = None
+        basic_memory.config._CONFIG_SIZE = None
 
         loaded = config_manager.load_config()
         assert loaded.default_project == "work"
@@ -545,6 +549,8 @@ class TestConfigManager:
             import basic_memory.config
 
             basic_memory.config._CONFIG_CACHE = None
+            basic_memory.config._CONFIG_MTIME = None
+            basic_memory.config._CONFIG_SIZE = None
 
             # Should load successfully with migration to ProjectEntry
             config = config_manager.load_config()
@@ -585,6 +591,8 @@ class TestConfigManager:
             import basic_memory.config
 
             basic_memory.config._CONFIG_CACHE = None
+            basic_memory.config._CONFIG_MTIME = None
+            basic_memory.config._CONFIG_SIZE = None
 
             config = config_manager.load_config()
 
@@ -617,6 +625,8 @@ class TestConfigManager:
             import basic_memory.config
 
             basic_memory.config._CONFIG_CACHE = None
+            basic_memory.config._CONFIG_MTIME = None
+            basic_memory.config._CONFIG_SIZE = None
 
             loaded = config_manager.load_config()
             assert isinstance(loaded, BasicMemoryConfig)
@@ -647,6 +657,8 @@ class TestConfigManager:
             import basic_memory.config
 
             basic_memory.config._CONFIG_CACHE = None
+            basic_memory.config._CONFIG_MTIME = None
+            basic_memory.config._CONFIG_SIZE = None
 
             config_manager.load_config()
 
@@ -678,6 +690,8 @@ class TestConfigManager:
             import basic_memory.config
 
             basic_memory.config._CONFIG_CACHE = None
+            basic_memory.config._CONFIG_MTIME = None
+            basic_memory.config._CONFIG_SIZE = None
 
             config_manager.load_config()
 
@@ -889,6 +903,22 @@ class TestSemanticSearchConfig:
         with pytest.raises(Exception):
             BasicMemoryConfig(semantic_min_similarity=1.1)
 
+    def test_default_search_type_defaults_to_none(self):
+        """default_search_type should be None by default (auto-detect)."""
+        config = BasicMemoryConfig()
+        assert config.default_search_type is None
+
+    def test_default_search_type_accepts_valid_values(self):
+        """default_search_type accepts text, vector, hybrid."""
+        for search_type in ("text", "vector", "hybrid"):
+            config = BasicMemoryConfig(default_search_type=search_type)
+            assert config.default_search_type == search_type
+
+    def test_default_search_type_rejects_invalid_values(self):
+        """default_search_type rejects unknown values."""
+        with pytest.raises(Exception):
+            BasicMemoryConfig(default_search_type="invalid")
+
 
 class TestFormattingConfig:
     """Test file formatting configuration options."""
@@ -1099,6 +1129,8 @@ class TestProjectMode:
             import basic_memory.config
 
             basic_memory.config._CONFIG_CACHE = None
+            basic_memory.config._CONFIG_MTIME = None
+            basic_memory.config._CONFIG_SIZE = None
 
             # Should load successfully with migration
             config = config_manager.load_config()
@@ -1174,6 +1206,116 @@ class TestProjectMode:
             assert loaded.projects["main"].workspace_id is None
 
 
+class TestConfigCacheMtimeInvalidation:
+    """Test that config cache is invalidated when file is modified externally."""
+
+    def test_cache_returns_same_config_when_file_unchanged(self, config_home):
+        """Verify cache hit when config file mtime has not changed."""
+        import basic_memory.config
+
+        basic_memory.config._CONFIG_CACHE = None
+        basic_memory.config._CONFIG_MTIME = None
+        basic_memory.config._CONFIG_SIZE = None
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_path = Path(temp_dir)
+            config_manager = ConfigManager()
+            config_manager.config_dir = temp_path / "basic-memory"
+            config_manager.config_file = config_manager.config_dir / "config.json"
+            config_manager.config_dir.mkdir(parents=True, exist_ok=True)
+
+            test_config = BasicMemoryConfig(
+                projects={"main": {"path": str(temp_path / "main")}},
+                default_project="main",
+            )
+            config_manager.save_config(test_config)
+
+            # First load populates cache
+            config1 = config_manager.load_config()
+            assert config1.default_project == "main"
+
+            # Second load should return cached config (same object)
+            config2 = config_manager.load_config()
+            assert config1 is config2
+
+    def test_cache_invalidated_when_file_modified(self, config_home):
+        """Verify cache miss when config file is modified by another process."""
+        import json
+        import os
+        import time
+
+        import basic_memory.config
+
+        basic_memory.config._CONFIG_CACHE = None
+        basic_memory.config._CONFIG_MTIME = None
+        basic_memory.config._CONFIG_SIZE = None
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_path = Path(temp_dir)
+            config_manager = ConfigManager()
+            config_manager.config_dir = temp_path / "basic-memory"
+            config_manager.config_file = config_manager.config_dir / "config.json"
+            config_manager.config_dir.mkdir(parents=True, exist_ok=True)
+
+            test_config = BasicMemoryConfig(
+                projects={"main": {"path": str(temp_path / "main")}},
+                default_project="main",
+            )
+            config_manager.save_config(test_config)
+
+            # First load populates cache
+            config1 = config_manager.load_config()
+            assert config1.get_project_mode("main") == ProjectMode.LOCAL
+
+            # Simulate external process modifying the config file
+            config_data = json.loads(config_manager.config_file.read_text())
+            config_data["projects"]["main"]["mode"] = "cloud"
+
+            # Ensure mtime actually changes (some filesystems have 1s granularity)
+            time.sleep(0.05)
+            config_manager.config_file.write_text(json.dumps(config_data, indent=2))
+            # Force mtime change on filesystems with coarse granularity
+            new_mtime = os.path.getmtime(config_manager.config_file) + 1
+            os.utime(config_manager.config_file, (new_mtime, new_mtime))
+
+            # Next load should detect mtime change and re-read
+            config2 = config_manager.load_config()
+            assert config2.get_project_mode("main") == ProjectMode.CLOUD
+            assert config1 is not config2
+
+    def test_save_config_resets_mtime(self, config_home):
+        """Verify save_config clears both cache and mtime."""
+        import basic_memory.config
+
+        basic_memory.config._CONFIG_CACHE = None
+        basic_memory.config._CONFIG_MTIME = None
+        basic_memory.config._CONFIG_SIZE = None
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_path = Path(temp_dir)
+            config_manager = ConfigManager()
+            config_manager.config_dir = temp_path / "basic-memory"
+            config_manager.config_file = config_manager.config_dir / "config.json"
+            config_manager.config_dir.mkdir(parents=True, exist_ok=True)
+
+            test_config = BasicMemoryConfig(
+                projects={"main": {"path": str(temp_path / "main")}},
+            )
+            config_manager.save_config(test_config)
+
+            # Load to populate cache
+            config_manager.load_config()
+            assert basic_memory.config._CONFIG_CACHE is not None
+            assert basic_memory.config._CONFIG_MTIME is not None
+            assert basic_memory.config._CONFIG_SIZE is not None
+
+            # Save should clear all cache state
+            config_manager.save_config(test_config)
+            assert basic_memory.config._CONFIG_CACHE is None
+            assert basic_memory.config._CONFIG_MTIME is None
+            assert basic_memory.config._CONFIG_SIZE is None
+
+
 class TestLocalSyncPathMigration:
     """Test migration that promotes local_sync_path into path for cloud projects."""
 
@@ -1237,3 +1379,47 @@ class TestLocalSyncPathMigration:
         assert result["projects"]["local-proj"]["path"] == local_path
         assert result["projects"]["cloud-only"]["path"] == "cloud-only"
         assert result["projects"]["cloud-bisync"]["path"] == bisync_path
+
+
+class TestAutoUpdateConfig:
+    """Test auto-update configuration fields."""
+
+    def test_auto_update_defaults(self):
+        """Auto-update should default on with a daily check interval."""
+        config = BasicMemoryConfig()
+        assert config.auto_update is True
+        assert config.update_check_interval == 86400
+        assert config.auto_update_last_checked_at is None
+
+    def test_auto_update_env_overrides(self, monkeypatch):
+        """Environment variables should override auto-update defaults."""
+        monkeypatch.setenv("BASIC_MEMORY_AUTO_UPDATE", "false")
+        monkeypatch.setenv("BASIC_MEMORY_UPDATE_CHECK_INTERVAL", "3600")
+
+        config = BasicMemoryConfig()
+        assert config.auto_update is False
+        assert config.update_check_interval == 3600
+
+    def test_auto_update_round_trip_persistence(self):
+        """Auto-update values should survive save/load cycle."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_path = Path(temp_dir)
+
+            config_manager = ConfigManager()
+            config_manager.config_dir = temp_path / "basic-memory"
+            config_manager.config_file = config_manager.config_dir / "config.json"
+            config_manager.config_dir.mkdir(parents=True, exist_ok=True)
+
+            checked_at = datetime.now()
+            test_config = BasicMemoryConfig(
+                projects={"main": {"path": str(temp_path / "main")}},
+                auto_update=False,
+                update_check_interval=7200,
+                auto_update_last_checked_at=checked_at,
+            )
+            config_manager.save_config(test_config)
+
+            loaded = config_manager.load_config()
+            assert loaded.auto_update is False
+            assert loaded.update_check_interval == 7200
+            assert loaded.auto_update_last_checked_at == checked_at

tests/test_telemetry.py

@@ -0,0 +1,296 @@
+"""Tests for optional Logfire bootstrap helpers."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import copy_context
+
+from loguru import logger
+from basic_memory import telemetry
+from basic_memory.config import init_api_logging, init_cli_logging, init_mcp_logging
+
+
+class FakeLogfire:
+    """Small fake Logfire surface for bootstrap testing."""
+
+    class CodeSource:
+        def __init__(self, **kwargs):
+            self.kwargs = kwargs
+
+    def __init__(self, *, fail_on_send_to_logfire: bool = False) -> None:
+        self.fail_on_send_to_logfire = fail_on_send_to_logfire
+        self.configure_calls: list[dict] = []
+        self.span_calls: list[tuple[str, dict]] = []
+
+    def configure(self, **kwargs) -> None:
+        self.configure_calls.append(kwargs)
+        if self.fail_on_send_to_logfire and "send_to_logfire" in kwargs:
+            raise TypeError("send_to_logfire not supported")
+
+    def loguru_handler(self) -> dict:
+        return {"sink": "fake-logfire", "level": "INFO"}
+
+    @contextmanager
+    def span(self, name: str, **attrs):
+        self.span_calls.append((name, attrs))
+        yield
+
+
+def test_configure_telemetry_disabled_is_noop() -> None:
+    telemetry.reset_telemetry_state()
+
+    enabled = telemetry.configure_telemetry(
+        "basic-memory-cli",
+        environment="dev",
+        enable_logfire=False,
+    )
+
+    assert enabled is False
+    assert telemetry.telemetry_enabled() is False
+    assert telemetry.get_logfire_handler() is None
+    assert telemetry.pop_telemetry_warnings() == []
+
+
+def test_configure_telemetry_warns_when_dependency_missing(monkeypatch) -> None:
+    telemetry.reset_telemetry_state()
+    monkeypatch.setattr(telemetry, "_load_logfire", lambda: None)
+
+    enabled = telemetry.configure_telemetry(
+        "basic-memory-cli",
+        environment="dev",
+        enable_logfire=True,
+    )
+
+    assert enabled is False
+    assert telemetry.telemetry_enabled() is False
+    assert telemetry.get_logfire_handler() is None
+    assert telemetry.pop_telemetry_warnings() == [
+        "Logfire telemetry was enabled but the 'logfire' package is not installed. "
+        "Telemetry remains disabled."
+    ]
+
+
+def test_configure_telemetry_retries_without_send_to_logfire(monkeypatch) -> None:
+    fake_logfire = FakeLogfire(fail_on_send_to_logfire=True)
+    telemetry.reset_telemetry_state()
+    monkeypatch.setattr(telemetry, "_load_logfire", lambda: fake_logfire)
+
+    enabled = telemetry.configure_telemetry(
+        "basic-memory-api",
+        environment="prod",
+        service_version="abc123",
+        enable_logfire=True,
+        send_to_logfire=True,
+    )
+
+    assert enabled is True
+    assert telemetry.telemetry_enabled() is True
+    assert telemetry.get_logfire_handler() == {"sink": "fake-logfire", "level": "INFO"}
+    assert len(fake_logfire.configure_calls) == 2
+    assert fake_logfire.configure_calls[0]["send_to_logfire"] is True
+    assert "send_to_logfire" not in fake_logfire.configure_calls[1]
+
+
+def test_bind_telemetry_context_filters_nulls() -> None:
+    bound = telemetry.bind_telemetry_context(project_name="main", workspace_id=None)
+    extra = bound._options[-1]  # type: ignore[attr-defined]
+    assert extra == {"project_name": "main"}
+
+
+def test_bind_telemetry_context_merges_active_context() -> None:
+    with telemetry.contextualize(project_name="main", route_mode="local_asgi"):
+        bound = telemetry.bind_telemetry_context(tool_name="write_note", workspace_id=None)
+
+    extra = bound._options[-1]  # type: ignore[attr-defined]
+    assert extra == {
+        "project_name": "main",
+        "route_mode": "local_asgi",
+        "tool_name": "write_note",
+    }
+
+
+def test_contextualize_adds_filtered_loguru_context() -> None:
+    records: list[dict] = []
+    sink_id = logger.add(lambda message: records.append(message.record["extra"].copy()))
+
+    try:
+        with telemetry.contextualize(project_name="main", workspace_id=None):
+            logger.info("inside telemetry context")
+    finally:
+        logger.remove(sink_id)
+
+    assert records == [{"project_name": "main"}]
+
+
+def test_contextualize_nested_contexts_merge_and_unwind() -> None:
+    records: list[dict] = []
+    sink_id = logger.add(lambda message: records.append(message.record["extra"].copy()))
+
+    try:
+        with telemetry.contextualize(project_name="main"):
+            logger.info("outer context")
+            with telemetry.contextualize(tool_name="write_note"):
+                logger.info("inner context")
+            logger.info("outer context restored")
+    finally:
+        logger.remove(sink_id)
+
+    assert records == [
+        {"project_name": "main"},
+        {"project_name": "main", "tool_name": "write_note"},
+        {"project_name": "main"},
+    ]
+
+
+def test_span_uses_logfire_when_enabled(monkeypatch) -> None:
+    fake_logfire = FakeLogfire()
+    telemetry.reset_telemetry_state()
+    monkeypatch.setattr(telemetry, "_load_logfire", lambda: fake_logfire)
+    telemetry.configure_telemetry(
+        "basic-memory-mcp",
+        environment="dev",
+        enable_logfire=True,
+    )
+
+    with telemetry.span("mcp.tool.write_note", project_name="main", workspace_id=None):
+        pass
+
+    assert fake_logfire.span_calls == [("mcp.tool.write_note", {"project_name": "main"})]
+
+
+def test_operation_creates_span_and_log_context(monkeypatch) -> None:
+    fake_logfire = FakeLogfire()
+    records: list[dict] = []
+    sink_id = logger.add(lambda message: records.append(message.record["extra"].copy()))
+
+    telemetry.reset_telemetry_state()
+    monkeypatch.setattr(telemetry, "_load_logfire", lambda: fake_logfire)
+    telemetry.configure_telemetry(
+        "basic-memory-cli",
+        environment="dev",
+        enable_logfire=True,
+    )
+
+    try:
+        with telemetry.operation(
+            "cli.command.status",
+            entrypoint="cli",
+            command_name="status",
+            workspace_id=None,
+        ):
+            logger.info("inside operation")
+    finally:
+        logger.remove(sink_id)
+
+    assert fake_logfire.span_calls == [
+        ("cli.command.status", {"entrypoint": "cli", "command_name": "status"})
+    ]
+    assert records == [{"entrypoint": "cli", "command_name": "status"}]
+
+
+def test_scope_creates_span_and_nested_log_context(monkeypatch) -> None:
+    fake_logfire = FakeLogfire()
+    records: list[dict] = []
+    sink_id = logger.add(lambda message: records.append(message.record["extra"].copy()))
+
+    telemetry.reset_telemetry_state()
+    monkeypatch.setattr(telemetry, "_load_logfire", lambda: fake_logfire)
+    telemetry.configure_telemetry(
+        "basic-memory-mcp",
+        environment="dev",
+        enable_logfire=True,
+    )
+
+    try:
+        with telemetry.contextualize(project_name="main"):
+            with telemetry.scope(
+                "routing.client_session",
+                route_mode="local_asgi",
+                workspace_id=None,
+            ):
+                logger.info("inside scope")
+    finally:
+        logger.remove(sink_id)
+
+    assert fake_logfire.span_calls == [
+        ("routing.client_session", {"route_mode": "local_asgi"})
+    ]
+    assert records == [{"project_name": "main", "route_mode": "local_asgi"}]
+
+
+def test_contextualize_isolated_per_context() -> None:
+    def read_extra() -> dict:
+        holder: list[dict] = []
+        sink_id = logger.add(lambda message: holder.append(message.record["extra"].copy()))
+        try:
+            logger.info("outside context")
+        finally:
+            logger.remove(sink_id)
+        return holder[0]
+
+    with telemetry.contextualize(project_name="main"):
+        inside = read_extra()
+
+    outside = copy_context().run(read_extra)
+
+    assert inside == {"project_name": "main"}
+    assert outside == {}
+
+
+def test_init_logging_functions_configure_telemetry_and_logging(monkeypatch) -> None:
+    telemetry_calls: list[dict] = []
+    setup_calls: list[dict] = []
+
+    class StubConfig:
+        logfire_enabled = True
+        logfire_send_to_logfire = False
+        logfire_service_name = "basic-memory"
+        logfire_environment = "staging"
+        env = "dev"
+
+    monkeypatch.setattr(
+        "basic_memory.config.ConfigManager", lambda: type("CM", (), {"config": StubConfig()})()
+    )
+    monkeypatch.setattr(
+        "basic_memory.config.configure_telemetry",
+        lambda **kwargs: telemetry_calls.append(kwargs),
+    )
+    monkeypatch.setattr(
+        "basic_memory.config.setup_logging",
+        lambda **kwargs: setup_calls.append(kwargs),
+    )
+    monkeypatch.setenv("BASIC_MEMORY_LOG_LEVEL", "DEBUG")
+    monkeypatch.delenv("BASIC_MEMORY_CLOUD_MODE", raising=False)
+
+    init_cli_logging()
+    init_mcp_logging()
+    init_api_logging()
+
+    assert telemetry_calls == [
+        {
+            "service_name": "basic-memory-cli",
+            "environment": "staging",
+            "service_version": "0.20.2",
+            "enable_logfire": True,
+            "send_to_logfire": False,
+        },
+        {
+            "service_name": "basic-memory-mcp",
+            "environment": "staging",
+            "service_version": "0.20.2",
+            "enable_logfire": True,
+            "send_to_logfire": False,
+        },
+        {
+            "service_name": "basic-memory-api",
+            "environment": "staging",
+            "service_version": "0.20.2",
+            "enable_logfire": True,
+            "send_to_logfire": False,
+        },
+    ]
+    assert setup_calls == [
+        {"log_level": "DEBUG", "log_to_file": True},
+        {"log_level": "DEBUG", "log_to_file": True},
+        {"log_level": "DEBUG", "log_to_file": True},
+    ]

tests/utils/test_file_utils.py

@@ -198,6 +198,19 @@ def test_sanitize_for_filename_removes_invalid_characters():
         assert char not in sanitized_text
 
 
+def test_sanitize_for_filename_strips_trailing_periods():
+    """Trailing periods cause double-dot filenames like 'hi-everyone..md'.
+
+    This was a production bug where title "Hi everyone." produced file path
+    "hi-everyone..md" which failed path traversal validation.
+    """
+    assert sanitize_for_filename("Hi everyone.") == "Hi everyone"
+    assert sanitize_for_filename("test...") == "test"
+    assert sanitize_for_filename(".hidden") == "hidden"
+    assert sanitize_for_filename("...dots...") == "dots"
+    assert sanitize_for_filename("normal title") == "normal title"
+
+
 @pytest.mark.parametrize(
     "input_directory,expected",
     [

tests/utils/test_setup_logging.py

@@ -0,0 +1,213 @@
+"""Tests for logging setup helpers."""
+
+import os
+import sys
+
+from basic_memory import utils
+
+
+def test_setup_logging_uses_shared_log_file_off_windows(monkeypatch, tmp_path) -> None:
+    """Non-Windows platforms should keep the shared log filename."""
+    added_sinks: list[str] = []
+
+    monkeypatch.setenv("BASIC_MEMORY_ENV", "dev")
+    monkeypatch.setattr(utils.os, "name", "posix")
+    monkeypatch.setattr(utils.Path, "home", lambda: tmp_path)
+    monkeypatch.setattr(utils.logger, "remove", lambda *args, **kwargs: None)
+    monkeypatch.setattr(
+        utils.logger,
+        "add",
+        lambda sink, **kwargs: added_sinks.append(str(sink)),
+    )
+    monkeypatch.setattr(utils.telemetry, "get_logfire_handler", lambda: None)
+    monkeypatch.setattr(utils.telemetry, "pop_telemetry_warnings", lambda: [])
+
+    utils.setup_logging(log_to_file=True)
+
+    assert added_sinks == [str(tmp_path / ".basic-memory" / "basic-memory.log")]
+
+
+def test_setup_logging_uses_per_process_log_file_on_windows(monkeypatch, tmp_path) -> None:
+    """Windows uses per-process logs so rotation never contends across processes."""
+    added_sinks: list[str] = []
+
+    monkeypatch.setenv("BASIC_MEMORY_ENV", "dev")
+    monkeypatch.setattr(utils.os, "name", "nt")
+    monkeypatch.setattr(utils.os, "getpid", lambda: 4242)
+    monkeypatch.setattr(utils.Path, "home", lambda: tmp_path)
+    monkeypatch.setattr(utils.logger, "remove", lambda *args, **kwargs: None)
+    monkeypatch.setattr(
+        utils.logger,
+        "add",
+        lambda sink, **kwargs: added_sinks.append(str(sink)),
+    )
+    monkeypatch.setattr(utils.telemetry, "get_logfire_handler", lambda: None)
+    monkeypatch.setattr(utils.telemetry, "pop_telemetry_warnings", lambda: [])
+
+    utils.setup_logging(log_to_file=True)
+
+    assert added_sinks == [str(tmp_path / ".basic-memory" / "basic-memory-4242.log")]
+
+
+def test_setup_logging_trims_stale_windows_pid_logs(monkeypatch, tmp_path) -> None:
+    """Windows cleanup should bound stale PID-specific log files across runs."""
+    log_dir = tmp_path / ".basic-memory"
+    log_dir.mkdir()
+
+    stale_logs = []
+    for index in range(6):
+        log_path = log_dir / f"basic-memory-{1000 + index}.log"
+        log_path.write_text("old log", encoding="utf-8")
+        mtime = 1_000 + index
+        os.utime(log_path, (mtime, mtime))
+        stale_logs.append(log_path)
+
+    monkeypatch.setenv("BASIC_MEMORY_ENV", "dev")
+    monkeypatch.setattr(utils.os, "name", "nt")
+    monkeypatch.setattr(utils.os, "getpid", lambda: 4242)
+    monkeypatch.setattr(utils.Path, "home", lambda: tmp_path)
+    monkeypatch.setattr(utils.logger, "remove", lambda *args, **kwargs: None)
+    monkeypatch.setattr(utils.logger, "add", lambda *args, **kwargs: None)
+    monkeypatch.setattr(utils.telemetry, "get_logfire_handler", lambda: None)
+    monkeypatch.setattr(utils.telemetry, "pop_telemetry_warnings", lambda: [])
+
+    utils.setup_logging(log_to_file=True)
+
+    remaining = sorted(path.name for path in log_dir.glob("basic-memory-*.log*"))
+    assert remaining == [
+        "basic-memory-1002.log",
+        "basic-memory-1003.log",
+        "basic-memory-1004.log",
+        "basic-memory-1005.log",
+    ]
+
+
+def test_setup_logging_test_env_uses_stderr_only(monkeypatch) -> None:
+    """Test mode should add one stderr sink and return before other branches run."""
+    added_sinks: list[object] = []
+    configured_calls: list[dict] = []
+
+    monkeypatch.setenv("BASIC_MEMORY_ENV", "test")
+    monkeypatch.setattr(utils.logger, "remove", lambda *args, **kwargs: None)
+    monkeypatch.setattr(utils.logger, "add", lambda sink, **kwargs: added_sinks.append(sink))
+    monkeypatch.setattr(
+        utils.logger,
+        "configure",
+        lambda **kwargs: configured_calls.append(kwargs),
+    )
+
+    utils.setup_logging(log_to_file=True, log_to_stdout=True, structured_context=True)
+
+    assert added_sinks == [sys.stderr]
+    assert configured_calls == []
+
+
+def test_setup_logging_log_to_stdout(monkeypatch) -> None:
+    """stdout logging should attach a stderr sink outside test mode."""
+    added_sinks: list[object] = []
+
+    monkeypatch.setenv("BASIC_MEMORY_ENV", "dev")
+    monkeypatch.setattr(utils.logger, "remove", lambda *args, **kwargs: None)
+    monkeypatch.setattr(utils.logger, "add", lambda sink, **kwargs: added_sinks.append(sink))
+    monkeypatch.setattr(utils.telemetry, "get_logfire_handler", lambda: None)
+    monkeypatch.setattr(utils.telemetry, "pop_telemetry_warnings", lambda: [])
+
+    utils.setup_logging(log_to_stdout=True)
+
+    assert added_sinks == [sys.stderr]
+
+
+def test_setup_logging_structured_context(monkeypatch) -> None:
+    """Structured context should bind cloud metadata into loguru extras."""
+    configured_extras: list[dict[str, str]] = []
+
+    monkeypatch.setenv("BASIC_MEMORY_ENV", "dev")
+    monkeypatch.setenv("BASIC_MEMORY_TENANT_ID", "tenant-123")
+    monkeypatch.setenv("FLY_APP_NAME", "bm-app")
+    monkeypatch.setenv("FLY_MACHINE_ID", "machine-123")
+    monkeypatch.setenv("FLY_REGION", "ord")
+    monkeypatch.setattr(utils.logger, "remove", lambda *args, **kwargs: None)
+    monkeypatch.setattr(utils.logger, "add", lambda *args, **kwargs: None)
+    monkeypatch.setattr(utils.telemetry, "get_logfire_handler", lambda: None)
+    monkeypatch.setattr(utils.telemetry, "pop_telemetry_warnings", lambda: [])
+    monkeypatch.setattr(
+        utils.logger,
+        "configure",
+        lambda **kwargs: configured_extras.append(kwargs["extra"]),
+    )
+
+    utils.setup_logging(structured_context=True)
+
+    assert configured_extras == [
+        {
+            "tenant_id": "tenant-123",
+            "fly_app_name": "bm-app",
+            "fly_machine_id": "machine-123",
+            "fly_region": "ord",
+        }
+    ]
+
+
+def test_setup_logging_suppresses_noisy_loggers(monkeypatch) -> None:
+    """Third-party HTTP/file-watch loggers should be raised to WARNING."""
+    monkeypatch.setenv("BASIC_MEMORY_ENV", "dev")
+    monkeypatch.setattr(utils.logger, "remove", lambda *args, **kwargs: None)
+    monkeypatch.setattr(utils.logger, "add", lambda *args, **kwargs: None)
+    monkeypatch.setattr(utils.telemetry, "get_logfire_handler", lambda: None)
+    monkeypatch.setattr(utils.telemetry, "pop_telemetry_warnings", lambda: [])
+
+    httpx_logger = utils.logging.getLogger("httpx")
+    watchfiles_logger = utils.logging.getLogger("watchfiles.main")
+    original_httpx_level = httpx_logger.level
+    original_watchfiles_level = watchfiles_logger.level
+
+    try:
+        httpx_logger.setLevel(utils.logging.DEBUG)
+        watchfiles_logger.setLevel(utils.logging.INFO)
+
+        utils.setup_logging()
+
+        assert httpx_logger.level == utils.logging.WARNING
+        assert watchfiles_logger.level == utils.logging.WARNING
+    finally:
+        httpx_logger.setLevel(original_httpx_level)
+        watchfiles_logger.setLevel(original_watchfiles_level)
+
+
+def test_setup_logging_adds_logfire_handler(monkeypatch) -> None:
+    """Configured Logfire handlers should be added as an extra Loguru sink."""
+    added_sinks: list[object] = []
+
+    monkeypatch.setenv("BASIC_MEMORY_ENV", "dev")
+    monkeypatch.setattr(utils.logger, "remove", lambda *args, **kwargs: None)
+    monkeypatch.setattr(utils.logger, "add", lambda sink, **kwargs: added_sinks.append(sink))
+    monkeypatch.setattr(
+        utils.telemetry,
+        "get_logfire_handler",
+        lambda: {"sink": "logfire-sink", "level": "INFO"},
+    )
+    monkeypatch.setattr(utils.telemetry, "pop_telemetry_warnings", lambda: [])
+
+    utils.setup_logging()
+
+    assert added_sinks == ["logfire-sink"]
+
+
+def test_setup_logging_emits_telemetry_warnings(monkeypatch) -> None:
+    """Telemetry warnings should be logged after sinks are configured."""
+    warnings_logged: list[str] = []
+
+    monkeypatch.setenv("BASIC_MEMORY_ENV", "dev")
+    monkeypatch.setattr(utils.logger, "remove", lambda *args, **kwargs: None)
+    monkeypatch.setattr(utils.logger, "add", lambda *args, **kwargs: None)
+    monkeypatch.setattr(utils.telemetry, "get_logfire_handler", lambda: None)
+    monkeypatch.setattr(
+        utils.telemetry,
+        "pop_telemetry_warnings",
+        lambda: ["telemetry warning 1", "telemetry warning 2"],
+    )
+    monkeypatch.setattr(utils.logger, "warning", lambda message: warnings_logged.append(message))
+
+    utils.setup_logging()
+
+    assert warnings_logged == ["telemetry warning 1", "telemetry warning 2"]

tests/utils/test_validate_project_path.py

@@ -191,6 +191,54 @@ class TestValidateProjectPathAttacks:
             assert not result, f"Absolute path '{path}' should be blocked"
 
 
+class TestValidateProjectPathDoubleDotInFilename:
+    """Test that filenames containing '..' as part of the name are allowed."""
+
+    def test_double_dot_in_filename_allowed(self, tmp_path):
+        """Filenames like 'hi-everyone..md' should NOT be blocked.
+
+        This was a production bug: a title ending with a period (e.g. "Hi everyone.")
+        produced a file path like "hi-everyone..md" which the old substring check
+        ('..' in path) incorrectly flagged as path traversal.
+        """
+        project_path = tmp_path / "project"
+        project_path.mkdir()
+
+        safe_paths_with_dots = [
+            "hi-everyone..md",
+            "notes/hi-everyone..md",
+            "version-2..0.md",
+            "file...name.md",
+            "docs/report..final.txt",
+        ]
+
+        for path in safe_paths_with_dots:
+            assert validate_project_path(path, project_path), (
+                f"Path '{path}' with '..' in filename should be allowed"
+            )
+
+    def test_actual_traversal_still_blocked(self, tmp_path):
+        """Ensure '..' as a path segment is still blocked."""
+        project_path = tmp_path / "project"
+        project_path.mkdir()
+
+        attack_paths = [
+            "../file.md",
+            "notes/../../etc/passwd",
+            "foo/../../../bar",
+            "..\\Windows\\System32",
+            # Windows normalizes trailing dots/spaces to ".."
+            ".. /file.md",
+            ".. ./file.md",
+            "notes/.. /etc/passwd",
+        ]
+
+        for path in attack_paths:
+            assert not validate_project_path(path, project_path), (
+                f"Traversal path '{path}' should still be blocked"
+            )
+
+
 class TestValidateProjectPathEdgeCases:
     """Test edge cases and error conditions."""
 

uv.lock

@@ -142,14 +142,14 @@ wheels = [
 
 [[package]]
 name = "authlib"
-version = "1.6.6"
+version = "1.6.7"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "cryptography" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/bb/9b/b1661026ff24bc641b76b78c5222d614776b0c085bcfdac9bd15a1cb4b35/authlib-1.6.6.tar.gz", hash = "sha256:45770e8e056d0f283451d9996fbb59b70d45722b45d854d58f32878d0a40c38e", size = 164894, upload-time = "2025-12-12T08:01:41.464Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/49/dc/ed1681bf1339dd6ea1ce56136bad4baabc6f7ad466e375810702b0237047/authlib-1.6.7.tar.gz", hash = "sha256:dbf10100011d1e1b34048c9d120e83f13b35d69a826ae762b93d2fb5aafc337b", size = 164950, upload-time = "2026-02-06T14:04:14.171Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/54/51/321e821856452f7386c4e9df866f196720b1ad0c5ea1623ea7399969ae3b/authlib-1.6.6-py2.py3-none-any.whl", hash = "sha256:7d9e9bc535c13974313a87f53e8430eb6ea3d1cf6ae4f6efcd793f2e949143fd", size = 244005, upload-time = "2025-12-12T08:01:40.209Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/00/3ed12264094ec91f534fae429945efbaa9f8c666f3aa7061cc3b2a26a0cd/authlib-1.6.7-py2.py3-none-any.whl", hash = "sha256:c637340d9a02789d2efa1d003a7437d10d3e565237bcb5fcbc6c134c7b95bab0", size = 244115, upload-time = "2026-02-06T14:04:12.141Z" },
 ]
 
 [[package]]
@@ -196,6 +196,11 @@ dependencies = [
     { name = "watchfiles" },
 ]
 
+[package.optional-dependencies]
+telemetry = [
+    { name = "logfire" },
+]
+
 [package.dev-dependencies]
 dev = [
     { name = "cst-lsp" },
@@ -203,6 +208,7 @@ dev = [
     { name = "gevent" },
     { name = "icecream" },
     { name = "libcst" },
+    { name = "logfire" },
     { name = "psycopg" },
     { name = "pyright" },
     { name = "pytest" },
@@ -229,6 +235,7 @@ requires-dist = [
     { name = "fastmcp", specifier = ">=3.0.1,<4" },
     { name = "greenlet", specifier = ">=3.1.1" },
     { name = "httpx", specifier = ">=0.28.0" },
+    { name = "logfire", marker = "extra == 'telemetry'", specifier = ">=4.19.0" },
     { name = "loguru", specifier = ">=0.7.3" },
     { name = "markdown-it-py", specifier = ">=3.0.0" },
     { name = "mcp", specifier = ">=1.23.1" },
@@ -257,6 +264,7 @@ requires-dist = [
     { name = "unidecode", specifier = ">=1.3.8" },
     { name = "watchfiles", specifier = ">=1.0.4" },
 ]
+provides-extras = ["telemetry"]
 
 [package.metadata.requires-dev]
 dev = [
@@ -265,6 +273,7 @@ dev = [
     { name = "gevent", specifier = ">=24.11.1" },
     { name = "icecream", specifier = ">=2.1.3" },
     { name = "libcst", specifier = ">=1.8.6" },
+    { name = "logfire", specifier = ">=4.19.0" },
     { name = "psycopg", specifier = ">=3.2.0" },
     { name = "pyright", specifier = ">=1.1.408" },
     { name = "pytest", specifier = ">=8.3.4" },
@@ -304,10 +313,16 @@ sdist = { url = "https://files.pythonhosted.org/packages/92/88/b8527e1b00c1811db
 wheels = [
     { url = "https://files.pythonhosted.org/packages/d3/25/79c98ebe12df31548ba4eaf44db11b7cad6b3e7b4203718335620939083c/caio-0.9.25-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:fb7ff95af4c31ad3f03179149aab61097a71fd85e05f89b4786de0359dffd044", size = 36983, upload-time = "2025-12-26T15:21:36.075Z" },
     { url = "https://files.pythonhosted.org/packages/a3/2b/21288691f16d479945968a0a4f2856818c1c5be56881d51d4dac9b255d26/caio-0.9.25-cp312-cp312-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:97084e4e30dfa598449d874c4d8e0c8d5ea17d2f752ef5e48e150ff9d240cd64", size = 82012, upload-time = "2025-12-26T15:22:20.983Z" },
+    { url = "https://files.pythonhosted.org/packages/03/c4/8a1b580875303500a9c12b9e0af58cb82e47f5bcf888c2457742a138273c/caio-0.9.25-cp312-cp312-manylinux_2_34_aarch64.whl", hash = "sha256:4fa69eba47e0f041b9d4f336e2ad40740681c43e686b18b191b6c5f4c5544bfb", size = 81502, upload-time = "2026-03-04T22:08:22.381Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/1c/0fe770b8ffc8362c48134d1592d653a81a3d8748d764bec33864db36319d/caio-0.9.25-cp312-cp312-manylinux_2_34_x86_64.whl", hash = "sha256:6bebf6f079f1341d19f7386db9b8b1f07e8cc15ae13bfdaff573371ba0575d69", size = 80200, upload-time = "2026-03-04T22:08:23.382Z" },
     { url = "https://files.pythonhosted.org/packages/31/57/5e6ff127e6f62c9f15d989560435c642144aa4210882f9494204bc892305/caio-0.9.25-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:d6c2a3411af97762a2b03840c3cec2f7f728921ff8adda53d7ea2315a8563451", size = 36979, upload-time = "2025-12-26T15:21:35.484Z" },
     { url = "https://files.pythonhosted.org/packages/a3/9f/f21af50e72117eb528c422d4276cbac11fb941b1b812b182e0a9c70d19c5/caio-0.9.25-cp313-cp313-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:0998210a4d5cd5cb565b32ccfe4e53d67303f868a76f212e002a8554692870e6", size = 81900, upload-time = "2025-12-26T15:22:21.919Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/12/c39ae2a4037cb10ad5eb3578eb4d5f8c1a2575c62bba675f3406b7ef0824/caio-0.9.25-cp313-cp313-manylinux_2_34_aarch64.whl", hash = "sha256:1a177d4777141b96f175fe2c37a3d96dec7911ed9ad5f02bac38aaa1c936611f", size = 81523, upload-time = "2026-03-04T22:08:25.187Z" },
+    { url = "https://files.pythonhosted.org/packages/22/59/f8f2e950eb4f1a5a3883e198dca514b9d475415cb6cd7b78b9213a0dd45a/caio-0.9.25-cp313-cp313-manylinux_2_34_x86_64.whl", hash = "sha256:9ed3cfb28c0e99fec5e208c934e5c157d0866aa9c32aa4dc5e9b6034af6286b7", size = 80243, upload-time = "2026-03-04T22:08:26.449Z" },
     { url = "https://files.pythonhosted.org/packages/69/ca/a08fdc7efdcc24e6a6131a93c85be1f204d41c58f474c42b0670af8c016b/caio-0.9.25-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:fab6078b9348e883c80a5e14b382e6ad6aabbc4429ca034e76e730cf464269db", size = 36978, upload-time = "2025-12-26T15:21:41.055Z" },
     { url = "https://files.pythonhosted.org/packages/5e/6c/d4d24f65e690213c097174d26eda6831f45f4734d9d036d81790a27e7b78/caio-0.9.25-cp314-cp314-manylinux2010_x86_64.manylinux2014_x86_64.manylinux_2_12_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:44a6b58e52d488c75cfaa5ecaa404b2b41cc965e6c417e03251e868ecd5b6d77", size = 81832, upload-time = "2025-12-26T15:22:22.757Z" },
+    { url = "https://files.pythonhosted.org/packages/87/a4/e534cf7d2d0e8d880e25dd61e8d921ffcfe15bd696734589826f5a2df727/caio-0.9.25-cp314-cp314-manylinux_2_34_aarch64.whl", hash = "sha256:628a630eb7fb22381dd8e3c8ab7f59e854b9c806639811fc3f4310c6bd711d79", size = 81565, upload-time = "2026-03-04T22:08:27.483Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/ed/bf81aeac1d290017e5e5ac3e880fd56ee15e50a6d0353986799d1bc5cfd5/caio-0.9.25-cp314-cp314-manylinux_2_34_x86_64.whl", hash = "sha256:0ba16aa605ccb174665357fc729cf500679c2d94d5f1458a6f0d5ca48f2060a7", size = 80071, upload-time = "2026-03-04T22:08:28.751Z" },
     { url = "https://files.pythonhosted.org/packages/86/93/1f76c8d1bafe3b0614e06b2195784a3765bbf7b0a067661af9e2dd47fc33/caio-0.9.25-py3-none-any.whl", hash = "sha256:06c0bb02d6b929119b1cfbe1ca403c768b2013a369e2db46bfa2a5761cf82e40", size = 19087, upload-time = "2025-12-26T15:22:00.221Z" },
 ]
 
@@ -993,6 +1008,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c2/69/a7c4ba2ffbc7c7dbf6d8b4f5d0f0a421f7815d229f4909854266c445a3d4/gevent-25.9.1-cp314-cp314-win_amd64.whl", hash = "sha256:bb63c0d6cb9950cc94036a4995b9cc4667b8915366613449236970f4394f94d7", size = 1703019, upload-time = "2025-09-17T19:30:55.272Z" },
 ]
 
+[[package]]
+name = "googleapis-common-protos"
+version = "1.73.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "protobuf" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/99/96/a0205167fa0154f4a542fd6925bdc63d039d88dab3588b875078107e6f06/googleapis_common_protos-1.73.0.tar.gz", hash = "sha256:778d07cd4fbeff84c6f7c72102f0daf98fa2bfd3fa8bea426edc545588da0b5a", size = 147323, upload-time = "2026-03-06T21:53:09.727Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/69/28/23eea8acd65972bbfe295ce3666b28ac510dfcb115fac089d3edb0feb00a/googleapis_common_protos-1.73.0-py3-none-any.whl", hash = "sha256:dfdaaa2e860f242046be561e6d6cb5c5f1541ae02cfbcb034371aadb2942b4e8", size = 297578, upload-time = "2026-03-06T21:52:33.933Z" },
+]
+
 [[package]]
 name = "greenlet"
 version = "3.3.0"
@@ -1444,6 +1471,24 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/98/6d/5d6a790a02eb0d9d36c4aed4f41b277497e6178900b2fa29c35353aa45ed/libcst-1.8.6-cp314-cp314t-win_arm64.whl", hash = "sha256:819c8081e2948635cab60c603e1bbdceccdfe19104a242530ad38a36222cb88f", size = 2065000, upload-time = "2025-11-03T22:33:16.257Z" },
 ]
 
+[[package]]
+name = "logfire"
+version = "4.29.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "executing" },
+    { name = "opentelemetry-exporter-otlp-proto-http" },
+    { name = "opentelemetry-instrumentation" },
+    { name = "opentelemetry-sdk" },
+    { name = "protobuf" },
+    { name = "rich" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8f/40/3d09fe09cfa63753feada2d41dd909ce0741dd5731014a4b3eb31bdee977/logfire-4.29.0.tar.gz", hash = "sha256:18a306a0b5744aee8ad0a8f5d6b3a47a6d8951c340eaecc42dc5d0224f4bdca0", size = 1057563, upload-time = "2026-03-13T15:30:24.343Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/73/aa/fb8102ea48924fbbb9dfced7bada5717875801808ad53f9a60b6b4fec440/logfire-4.29.0-py3-none-any.whl", hash = "sha256:8dd7fdf6bed21459b8893eaa290d61977b9ebcc901844e365ddee868b5d8bca8", size = 302227, upload-time = "2026-03-13T15:30:20.742Z" },
+]
+
 [[package]]
 name = "loguru"
 version = "0.7.3"
@@ -1895,6 +1940,90 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cf/df/d3f1ddf4bb4cb50ed9b1139cc7b1c54c34a1e7ce8fd1b9a37c0d1551a6bd/opentelemetry_api-1.39.1-py3-none-any.whl", hash = "sha256:2edd8463432a7f8443edce90972169b195e7d6a05500cd29e6d13898187c9950", size = 66356, upload-time = "2025-12-11T13:32:17.304Z" },
 ]
 
+[[package]]
+name = "opentelemetry-exporter-otlp-proto-common"
+version = "1.39.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-proto" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e9/9d/22d241b66f7bbde88a3bfa6847a351d2c46b84de23e71222c6aae25c7050/opentelemetry_exporter_otlp_proto_common-1.39.1.tar.gz", hash = "sha256:763370d4737a59741c89a67b50f9e39271639ee4afc999dadfe768541c027464", size = 20409, upload-time = "2025-12-11T13:32:40.885Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8c/02/ffc3e143d89a27ac21fd557365b98bd0653b98de8a101151d5805b5d4c33/opentelemetry_exporter_otlp_proto_common-1.39.1-py3-none-any.whl", hash = "sha256:08f8a5862d64cc3435105686d0216c1365dc5701f86844a8cd56597d0c764fde", size = 18366, upload-time = "2025-12-11T13:32:20.2Z" },
+]
+
+[[package]]
+name = "opentelemetry-exporter-otlp-proto-http"
+version = "1.39.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "googleapis-common-protos" },
+    { name = "opentelemetry-api" },
+    { name = "opentelemetry-exporter-otlp-proto-common" },
+    { name = "opentelemetry-proto" },
+    { name = "opentelemetry-sdk" },
+    { name = "requests" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/80/04/2a08fa9c0214ae38880df01e8bfae12b067ec0793446578575e5080d6545/opentelemetry_exporter_otlp_proto_http-1.39.1.tar.gz", hash = "sha256:31bdab9745c709ce90a49a0624c2bd445d31a28ba34275951a6a362d16a0b9cb", size = 17288, upload-time = "2025-12-11T13:32:42.029Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/95/f1/b27d3e2e003cd9a3592c43d099d2ed8d0a947c15281bf8463a256db0b46c/opentelemetry_exporter_otlp_proto_http-1.39.1-py3-none-any.whl", hash = "sha256:d9f5207183dd752a412c4cd564ca8875ececba13be6e9c6c370ffb752fd59985", size = 19641, upload-time = "2025-12-11T13:32:22.248Z" },
+]
+
+[[package]]
+name = "opentelemetry-instrumentation"
+version = "0.60b1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "opentelemetry-semantic-conventions" },
+    { name = "packaging" },
+    { name = "wrapt" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/41/0f/7e6b713ac117c1f5e4e3300748af699b9902a2e5e34c9cf443dde25a01fa/opentelemetry_instrumentation-0.60b1.tar.gz", hash = "sha256:57ddc7974c6eb35865af0426d1a17132b88b2ed8586897fee187fd5b8944bd6a", size = 31706, upload-time = "2025-12-11T13:36:42.515Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/77/d2/6788e83c5c86a2690101681aeef27eeb2a6bf22df52d3f263a22cee20915/opentelemetry_instrumentation-0.60b1-py3-none-any.whl", hash = "sha256:04480db952b48fb1ed0073f822f0ee26012b7be7c3eac1a3793122737c78632d", size = 33096, upload-time = "2025-12-11T13:35:33.067Z" },
+]
+
+[[package]]
+name = "opentelemetry-proto"
+version = "1.39.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "protobuf" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/49/1d/f25d76d8260c156c40c97c9ed4511ec0f9ce353f8108ca6e7561f82a06b2/opentelemetry_proto-1.39.1.tar.gz", hash = "sha256:6c8e05144fc0d3ed4d22c2289c6b126e03bcd0e6a7da0f16cedd2e1c2772e2c8", size = 46152, upload-time = "2025-12-11T13:32:48.681Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/51/95/b40c96a7b5203005a0b03d8ce8cd212ff23f1793d5ba289c87a097571b18/opentelemetry_proto-1.39.1-py3-none-any.whl", hash = "sha256:22cdc78efd3b3765d09e68bfbd010d4fc254c9818afd0b6b423387d9dee46007", size = 72535, upload-time = "2025-12-11T13:32:33.866Z" },
+]
+
+[[package]]
+name = "opentelemetry-sdk"
+version = "1.39.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "opentelemetry-semantic-conventions" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/eb/fb/c76080c9ba07e1e8235d24cdcc4d125ef7aa3edf23eb4e497c2e50889adc/opentelemetry_sdk-1.39.1.tar.gz", hash = "sha256:cf4d4563caf7bff906c9f7967e2be22d0d6b349b908be0d90fb21c8e9c995cc6", size = 171460, upload-time = "2025-12-11T13:32:49.369Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7c/98/e91cf858f203d86f4eccdf763dcf01cf03f1dae80c3750f7e635bfa206b6/opentelemetry_sdk-1.39.1-py3-none-any.whl", hash = "sha256:4d5482c478513ecb0a5d938dcc61394e647066e0cc2676bee9f3af3f3f45f01c", size = 132565, upload-time = "2025-12-11T13:32:35.069Z" },
+]
+
+[[package]]
+name = "opentelemetry-semantic-conventions"
+version = "0.60b1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/91/df/553f93ed38bf22f4b999d9be9c185adb558982214f33eae539d3b5cd0858/opentelemetry_semantic_conventions-0.60b1.tar.gz", hash = "sha256:87c228b5a0669b748c76d76df6c364c369c28f1c465e50f661e39737e84bc953", size = 137935, upload-time = "2025-12-11T13:32:50.487Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7a/5e/5958555e09635d09b75de3c4f8b9cae7335ca545d77392ffe7331534c402/opentelemetry_semantic_conventions-0.60b1-py3-none-any.whl", hash = "sha256:9fa8c8b0c110da289809292b0591220d3a7b53c1526a23021e977d68597893fb", size = 219982, upload-time = "2025-12-11T13:32:36.955Z" },
+]
+
 [[package]]
 name = "packaging"
 version = "25.0"
@@ -3347,71 +3476,51 @@ wheels = [
 
 [[package]]
 name = "wrapt"
-version = "2.0.1"
+version = "1.17.3"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/49/2a/6de8a50cb435b7f42c46126cf1a54b2aab81784e74c8595c8e025e8f36d3/wrapt-2.0.1.tar.gz", hash = "sha256:9c9c635e78497cacb81e84f8b11b23e0aacac7a136e73b8e5b2109a1d9fc468f", size = 82040, upload-time = "2025-11-07T00:45:33.312Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/95/8f/aeb76c5b46e273670962298c23e7ddde79916cb74db802131d49a85e4b7d/wrapt-1.17.3.tar.gz", hash = "sha256:f66eb08feaa410fe4eebd17f2a2c8e2e46d3476e9f8c783daa8e09e0faa666d0", size = 55547, upload-time = "2025-08-12T05:53:21.714Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/cb/73/8cb252858dc8254baa0ce58ce382858e3a1cf616acebc497cb13374c95c6/wrapt-2.0.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:1fdbb34da15450f2b1d735a0e969c24bdb8d8924892380126e2a293d9902078c", size = 78129, upload-time = "2025-11-07T00:43:48.852Z" },
-    { url = "https://files.pythonhosted.org/packages/19/42/44a0db2108526ee6e17a5ab72478061158f34b08b793df251d9fbb9a7eb4/wrapt-2.0.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:3d32794fe940b7000f0519904e247f902f0149edbe6316c710a8562fb6738841", size = 61205, upload-time = "2025-11-07T00:43:50.402Z" },
-    { url = "https://files.pythonhosted.org/packages/4d/8a/5b4b1e44b791c22046e90d9b175f9a7581a8cc7a0debbb930f81e6ae8e25/wrapt-2.0.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:386fb54d9cd903ee0012c09291336469eb7b244f7183d40dc3e86a16a4bace62", size = 61692, upload-time = "2025-11-07T00:43:51.678Z" },
-    { url = "https://files.pythonhosted.org/packages/11/53/3e794346c39f462bcf1f58ac0487ff9bdad02f9b6d5ee2dc84c72e0243b2/wrapt-2.0.1-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:7b219cb2182f230676308cdcacd428fa837987b89e4b7c5c9025088b8a6c9faf", size = 121492, upload-time = "2025-11-07T00:43:55.017Z" },
-    { url = "https://files.pythonhosted.org/packages/c6/7e/10b7b0e8841e684c8ca76b462a9091c45d62e8f2de9c4b1390b690eadf16/wrapt-2.0.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:641e94e789b5f6b4822bb8d8ebbdfc10f4e4eae7756d648b717d980f657a9eb9", size = 123064, upload-time = "2025-11-07T00:43:56.323Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/d1/3c1e4321fc2f5ee7fd866b2d822aa89b84495f28676fd976c47327c5b6aa/wrapt-2.0.1-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:fe21b118b9f58859b5ebaa4b130dee18669df4bd111daad082b7beb8799ad16b", size = 117403, upload-time = "2025-11-07T00:43:53.258Z" },
-    { url = "https://files.pythonhosted.org/packages/a4/b0/d2f0a413cf201c8c2466de08414a15420a25aa83f53e647b7255cc2fab5d/wrapt-2.0.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:17fb85fa4abc26a5184d93b3efd2dcc14deb4b09edcdb3535a536ad34f0b4dba", size = 121500, upload-time = "2025-11-07T00:43:57.468Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/45/bddb11d28ca39970a41ed48a26d210505120f925918592283369219f83cc/wrapt-2.0.1-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:b89ef9223d665ab255ae42cc282d27d69704d94be0deffc8b9d919179a609684", size = 116299, upload-time = "2025-11-07T00:43:58.877Z" },
-    { url = "https://files.pythonhosted.org/packages/81/af/34ba6dd570ef7a534e7eec0c25e2615c355602c52aba59413411c025a0cb/wrapt-2.0.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:a453257f19c31b31ba593c30d997d6e5be39e3b5ad9148c2af5a7314061c63eb", size = 120622, upload-time = "2025-11-07T00:43:59.962Z" },
-    { url = "https://files.pythonhosted.org/packages/e2/3e/693a13b4146646fb03254636f8bafd20c621955d27d65b15de07ab886187/wrapt-2.0.1-cp312-cp312-win32.whl", hash = "sha256:3e271346f01e9c8b1130a6a3b0e11908049fe5be2d365a5f402778049147e7e9", size = 58246, upload-time = "2025-11-07T00:44:03.169Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/36/715ec5076f925a6be95f37917b66ebbeaa1372d1862c2ccd7a751574b068/wrapt-2.0.1-cp312-cp312-win_amd64.whl", hash = "sha256:2da620b31a90cdefa9cd0c2b661882329e2e19d1d7b9b920189956b76c564d75", size = 60492, upload-time = "2025-11-07T00:44:01.027Z" },
-    { url = "https://files.pythonhosted.org/packages/ef/3e/62451cd7d80f65cc125f2b426b25fbb6c514bf6f7011a0c3904fc8c8df90/wrapt-2.0.1-cp312-cp312-win_arm64.whl", hash = "sha256:aea9c7224c302bc8bfc892b908537f56c430802560e827b75ecbde81b604598b", size = 58987, upload-time = "2025-11-07T00:44:02.095Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/fe/41af4c46b5e498c90fc87981ab2972fbd9f0bccda597adb99d3d3441b94b/wrapt-2.0.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:47b0f8bafe90f7736151f61482c583c86b0693d80f075a58701dd1549b0010a9", size = 78132, upload-time = "2025-11-07T00:44:04.628Z" },
-    { url = "https://files.pythonhosted.org/packages/1c/92/d68895a984a5ebbbfb175512b0c0aad872354a4a2484fbd5552e9f275316/wrapt-2.0.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:cbeb0971e13b4bd81d34169ed57a6dda017328d1a22b62fda45e1d21dd06148f", size = 61211, upload-time = "2025-11-07T00:44:05.626Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/26/ba83dc5ae7cf5aa2b02364a3d9cf74374b86169906a1f3ade9a2d03cf21c/wrapt-2.0.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:eb7cffe572ad0a141a7886a1d2efa5bef0bf7fe021deeea76b3ab334d2c38218", size = 61689, upload-time = "2025-11-07T00:44:06.719Z" },
-    { url = "https://files.pythonhosted.org/packages/cf/67/d7a7c276d874e5d26738c22444d466a3a64ed541f6ef35f740dbd865bab4/wrapt-2.0.1-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:c8d60527d1ecfc131426b10d93ab5d53e08a09c5fa0175f6b21b3252080c70a9", size = 121502, upload-time = "2025-11-07T00:44:09.557Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/6b/806dbf6dd9579556aab22fc92908a876636e250f063f71548a8660382184/wrapt-2.0.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c654eafb01afac55246053d67a4b9a984a3567c3808bb7df2f8de1c1caba2e1c", size = 123110, upload-time = "2025-11-07T00:44:10.64Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/08/cdbb965fbe4c02c5233d185d070cabed2ecc1f1e47662854f95d77613f57/wrapt-2.0.1-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:98d873ed6c8b4ee2418f7afce666751854d6d03e3c0ec2a399bb039cd2ae89db", size = 117434, upload-time = "2025-11-07T00:44:08.138Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/d1/6aae2ce39db4cb5216302fa2e9577ad74424dfbe315bd6669725569e048c/wrapt-2.0.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:c9e850f5b7fc67af856ff054c71690d54fa940c3ef74209ad9f935b4f66a0233", size = 121533, upload-time = "2025-11-07T00:44:12.142Z" },
-    { url = "https://files.pythonhosted.org/packages/79/35/565abf57559fbe0a9155c29879ff43ce8bd28d2ca61033a3a3dd67b70794/wrapt-2.0.1-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:e505629359cb5f751e16e30cf3f91a1d3ddb4552480c205947da415d597f7ac2", size = 116324, upload-time = "2025-11-07T00:44:13.28Z" },
-    { url = "https://files.pythonhosted.org/packages/e1/e0/53ff5e76587822ee33e560ad55876d858e384158272cd9947abdd4ad42ca/wrapt-2.0.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:2879af909312d0baf35f08edeea918ee3af7ab57c37fe47cb6a373c9f2749c7b", size = 120627, upload-time = "2025-11-07T00:44:14.431Z" },
-    { url = "https://files.pythonhosted.org/packages/7c/7b/38df30fd629fbd7612c407643c63e80e1c60bcc982e30ceeae163a9800e7/wrapt-2.0.1-cp313-cp313-win32.whl", hash = "sha256:d67956c676be5a24102c7407a71f4126d30de2a569a1c7871c9f3cabc94225d7", size = 58252, upload-time = "2025-11-07T00:44:17.814Z" },
-    { url = "https://files.pythonhosted.org/packages/85/64/d3954e836ea67c4d3ad5285e5c8fd9d362fd0a189a2db622df457b0f4f6a/wrapt-2.0.1-cp313-cp313-win_amd64.whl", hash = "sha256:9ca66b38dd642bf90c59b6738af8070747b610115a39af2498535f62b5cdc1c3", size = 60500, upload-time = "2025-11-07T00:44:15.561Z" },
-    { url = "https://files.pythonhosted.org/packages/89/4e/3c8b99ac93527cfab7f116089db120fef16aac96e5f6cdb724ddf286086d/wrapt-2.0.1-cp313-cp313-win_arm64.whl", hash = "sha256:5a4939eae35db6b6cec8e7aa0e833dcca0acad8231672c26c2a9ab7a0f8ac9c8", size = 58993, upload-time = "2025-11-07T00:44:16.65Z" },
-    { url = "https://files.pythonhosted.org/packages/f9/f4/eff2b7d711cae20d220780b9300faa05558660afb93f2ff5db61fe725b9a/wrapt-2.0.1-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:a52f93d95c8d38fed0669da2ebdb0b0376e895d84596a976c15a9eb45e3eccb3", size = 82028, upload-time = "2025-11-07T00:44:18.944Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/67/cb945563f66fd0f61a999339460d950f4735c69f18f0a87ca586319b1778/wrapt-2.0.1-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:4e54bbf554ee29fcceee24fa41c4d091398b911da6e7f5d7bffda963c9aed2e1", size = 62949, upload-time = "2025-11-07T00:44:20.074Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/ca/f63e177f0bbe1e5cf5e8d9b74a286537cd709724384ff20860f8f6065904/wrapt-2.0.1-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:908f8c6c71557f4deaa280f55d0728c3bca0960e8c3dd5ceeeafb3c19942719d", size = 63681, upload-time = "2025-11-07T00:44:21.345Z" },
-    { url = "https://files.pythonhosted.org/packages/39/a1/1b88fcd21fd835dca48b556daef750952e917a2794fa20c025489e2e1f0f/wrapt-2.0.1-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:e2f84e9af2060e3904a32cea9bb6db23ce3f91cfd90c6b426757cf7cc01c45c7", size = 152696, upload-time = "2025-11-07T00:44:24.318Z" },
-    { url = "https://files.pythonhosted.org/packages/62/1c/d9185500c1960d9f5f77b9c0b890b7fc62282b53af7ad1b6bd779157f714/wrapt-2.0.1-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e3612dc06b436968dfb9142c62e5dfa9eb5924f91120b3c8ff501ad878f90eb3", size = 158859, upload-time = "2025-11-07T00:44:25.494Z" },
-    { url = "https://files.pythonhosted.org/packages/91/60/5d796ed0f481ec003220c7878a1d6894652efe089853a208ea0838c13086/wrapt-2.0.1-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:6d2d947d266d99a1477cd005b23cbd09465276e302515e122df56bb9511aca1b", size = 146068, upload-time = "2025-11-07T00:44:22.81Z" },
-    { url = "https://files.pythonhosted.org/packages/04/f8/75282dd72f102ddbfba137e1e15ecba47b40acff32c08ae97edbf53f469e/wrapt-2.0.1-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:7d539241e87b650cbc4c3ac9f32c8d1ac8a54e510f6dca3f6ab60dcfd48c9b10", size = 155724, upload-time = "2025-11-07T00:44:26.634Z" },
-    { url = "https://files.pythonhosted.org/packages/5a/27/fe39c51d1b344caebb4a6a9372157bdb8d25b194b3561b52c8ffc40ac7d1/wrapt-2.0.1-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:4811e15d88ee62dbf5c77f2c3ff3932b1e3ac92323ba3912f51fc4016ce81ecf", size = 144413, upload-time = "2025-11-07T00:44:27.939Z" },
-    { url = "https://files.pythonhosted.org/packages/83/2b/9f6b643fe39d4505c7bf926d7c2595b7cb4b607c8c6b500e56c6b36ac238/wrapt-2.0.1-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:c1c91405fcf1d501fa5d55df21e58ea49e6b879ae829f1039faaf7e5e509b41e", size = 150325, upload-time = "2025-11-07T00:44:29.29Z" },
-    { url = "https://files.pythonhosted.org/packages/bb/b6/20ffcf2558596a7f58a2e69c89597128781f0b88e124bf5a4cadc05b8139/wrapt-2.0.1-cp313-cp313t-win32.whl", hash = "sha256:e76e3f91f864e89db8b8d2a8311d57df93f01ad6bb1e9b9976d1f2e83e18315c", size = 59943, upload-time = "2025-11-07T00:44:33.211Z" },
-    { url = "https://files.pythonhosted.org/packages/87/6a/0e56111cbb3320151eed5d3821ee1373be13e05b376ea0870711f18810c3/wrapt-2.0.1-cp313-cp313t-win_amd64.whl", hash = "sha256:83ce30937f0ba0d28818807b303a412440c4b63e39d3d8fc036a94764b728c92", size = 63240, upload-time = "2025-11-07T00:44:30.935Z" },
-    { url = "https://files.pythonhosted.org/packages/1d/54/5ab4c53ea1f7f7e5c3e7c1095db92932cc32fd62359d285486d00c2884c3/wrapt-2.0.1-cp313-cp313t-win_arm64.whl", hash = "sha256:4b55cacc57e1dc2d0991dbe74c6419ffd415fb66474a02335cb10efd1aa3f84f", size = 60416, upload-time = "2025-11-07T00:44:32.002Z" },
-    { url = "https://files.pythonhosted.org/packages/73/81/d08d83c102709258e7730d3cd25befd114c60e43ef3891d7e6877971c514/wrapt-2.0.1-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:5e53b428f65ece6d9dad23cb87e64506392b720a0b45076c05354d27a13351a1", size = 78290, upload-time = "2025-11-07T00:44:34.691Z" },
-    { url = "https://files.pythonhosted.org/packages/f6/14/393afba2abb65677f313aa680ff0981e829626fed39b6a7e3ec807487790/wrapt-2.0.1-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:ad3ee9d0f254851c71780966eb417ef8e72117155cff04821ab9b60549694a55", size = 61255, upload-time = "2025-11-07T00:44:35.762Z" },
-    { url = "https://files.pythonhosted.org/packages/c4/10/a4a1f2fba205a9462e36e708ba37e5ac95f4987a0f1f8fd23f0bf1fc3b0f/wrapt-2.0.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:d7b822c61ed04ee6ad64bc90d13368ad6eb094db54883b5dde2182f67a7f22c0", size = 61797, upload-time = "2025-11-07T00:44:37.22Z" },
-    { url = "https://files.pythonhosted.org/packages/12/db/99ba5c37cf1c4fad35349174f1e38bd8d992340afc1ff27f526729b98986/wrapt-2.0.1-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:7164a55f5e83a9a0b031d3ffab4d4e36bbec42e7025db560f225489fa929e509", size = 120470, upload-time = "2025-11-07T00:44:39.425Z" },
-    { url = "https://files.pythonhosted.org/packages/30/3f/a1c8d2411eb826d695fc3395a431757331582907a0ec59afce8fe8712473/wrapt-2.0.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e60690ba71a57424c8d9ff28f8d006b7ad7772c22a4af432188572cd7fa004a1", size = 122851, upload-time = "2025-11-07T00:44:40.582Z" },
-    { url = "https://files.pythonhosted.org/packages/b3/8d/72c74a63f201768d6a04a8845c7976f86be6f5ff4d74996c272cefc8dafc/wrapt-2.0.1-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3cd1a4bd9a7a619922a8557e1318232e7269b5fb69d4ba97b04d20450a6bf970", size = 117433, upload-time = "2025-11-07T00:44:38.313Z" },
-    { url = "https://files.pythonhosted.org/packages/c7/5a/df37cf4042cb13b08256f8e27023e2f9b3d471d553376616591bb99bcb31/wrapt-2.0.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:b4c2e3d777e38e913b8ce3a6257af72fb608f86a1df471cb1d4339755d0a807c", size = 121280, upload-time = "2025-11-07T00:44:41.69Z" },
-    { url = "https://files.pythonhosted.org/packages/54/34/40d6bc89349f9931e1186ceb3e5fbd61d307fef814f09fbbac98ada6a0c8/wrapt-2.0.1-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:3d366aa598d69416b5afedf1faa539fac40c1d80a42f6b236c88c73a3c8f2d41", size = 116343, upload-time = "2025-11-07T00:44:43.013Z" },
-    { url = "https://files.pythonhosted.org/packages/70/66/81c3461adece09d20781dee17c2366fdf0cb8754738b521d221ca056d596/wrapt-2.0.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:c235095d6d090aa903f1db61f892fffb779c1eaeb2a50e566b52001f7a0f66ed", size = 119650, upload-time = "2025-11-07T00:44:44.523Z" },
-    { url = "https://files.pythonhosted.org/packages/46/3a/d0146db8be8761a9e388cc9cc1c312b36d583950ec91696f19bbbb44af5a/wrapt-2.0.1-cp314-cp314-win32.whl", hash = "sha256:bfb5539005259f8127ea9c885bdc231978c06b7a980e63a8a61c8c4c979719d0", size = 58701, upload-time = "2025-11-07T00:44:48.277Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/38/5359da9af7d64554be63e9046164bd4d8ff289a2dd365677d25ba3342c08/wrapt-2.0.1-cp314-cp314-win_amd64.whl", hash = "sha256:4ae879acc449caa9ed43fc36ba08392b9412ee67941748d31d94e3cedb36628c", size = 60947, upload-time = "2025-11-07T00:44:46.086Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/3f/96db0619276a833842bf36343685fa04f987dd6e3037f314531a1e00492b/wrapt-2.0.1-cp314-cp314-win_arm64.whl", hash = "sha256:8639b843c9efd84675f1e100ed9e99538ebea7297b62c4b45a7042edb84db03e", size = 59359, upload-time = "2025-11-07T00:44:47.164Z" },
-    { url = "https://files.pythonhosted.org/packages/71/49/5f5d1e867bf2064bf3933bc6cf36ade23505f3902390e175e392173d36a2/wrapt-2.0.1-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:9219a1d946a9b32bb23ccae66bdb61e35c62773ce7ca6509ceea70f344656b7b", size = 82031, upload-time = "2025-11-07T00:44:49.4Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/89/0009a218d88db66ceb83921e5685e820e2c61b59bbbb1324ba65342668bc/wrapt-2.0.1-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:fa4184e74197af3adad3c889a1af95b53bb0466bced92ea99a0c014e48323eec", size = 62952, upload-time = "2025-11-07T00:44:50.74Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/18/9b968e920dd05d6e44bcc918a046d02afea0fb31b2f1c80ee4020f377cbe/wrapt-2.0.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c5ef2f2b8a53b7caee2f797ef166a390fef73979b15778a4a153e4b5fedce8fa", size = 63688, upload-time = "2025-11-07T00:44:52.248Z" },
-    { url = "https://files.pythonhosted.org/packages/a6/7d/78bdcb75826725885d9ea26c49a03071b10c4c92da93edda612910f150e4/wrapt-2.0.1-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:e042d653a4745be832d5aa190ff80ee4f02c34b21f4b785745eceacd0907b815", size = 152706, upload-time = "2025-11-07T00:44:54.613Z" },
-    { url = "https://files.pythonhosted.org/packages/dd/77/cac1d46f47d32084a703df0d2d29d47e7eb2a7d19fa5cbca0e529ef57659/wrapt-2.0.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2afa23318136709c4b23d87d543b425c399887b4057936cd20386d5b1422b6fa", size = 158866, upload-time = "2025-11-07T00:44:55.79Z" },
-    { url = "https://files.pythonhosted.org/packages/8a/11/b521406daa2421508903bf8d5e8b929216ec2af04839db31c0a2c525eee0/wrapt-2.0.1-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:6c72328f668cf4c503ffcf9434c2b71fdd624345ced7941bc6693e61bbe36bef", size = 146148, upload-time = "2025-11-07T00:44:53.388Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/c0/340b272bed297baa7c9ce0c98ef7017d9c035a17a6a71dce3184b8382da2/wrapt-2.0.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:3793ac154afb0e5b45d1233cb94d354ef7a983708cc3bb12563853b1d8d53747", size = 155737, upload-time = "2025-11-07T00:44:56.971Z" },
-    { url = "https://files.pythonhosted.org/packages/f3/93/bfcb1fb2bdf186e9c2883a4d1ab45ab099c79cbf8f4e70ea453811fa3ea7/wrapt-2.0.1-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:fec0d993ecba3991645b4857837277469c8cc4c554a7e24d064d1ca291cfb81f", size = 144451, upload-time = "2025-11-07T00:44:58.515Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/6b/dca504fb18d971139d232652656180e3bd57120e1193d9a5899c3c0b7cdd/wrapt-2.0.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:949520bccc1fa227274da7d03bf238be15389cd94e32e4297b92337df9b7a349", size = 150353, upload-time = "2025-11-07T00:44:59.753Z" },
-    { url = "https://files.pythonhosted.org/packages/1d/f6/a1de4bd3653afdf91d250ca5c721ee51195df2b61a4603d4b373aa804d1d/wrapt-2.0.1-cp314-cp314t-win32.whl", hash = "sha256:be9e84e91d6497ba62594158d3d31ec0486c60055c49179edc51ee43d095f79c", size = 60609, upload-time = "2025-11-07T00:45:03.315Z" },
-    { url = "https://files.pythonhosted.org/packages/01/3a/07cd60a9d26fe73efead61c7830af975dfdba8537632d410462672e4432b/wrapt-2.0.1-cp314-cp314t-win_amd64.whl", hash = "sha256:61c4956171c7434634401db448371277d07032a81cc21c599c22953374781395", size = 64038, upload-time = "2025-11-07T00:45:00.948Z" },
-    { url = "https://files.pythonhosted.org/packages/41/99/8a06b8e17dddbf321325ae4eb12465804120f699cd1b8a355718300c62da/wrapt-2.0.1-cp314-cp314t-win_arm64.whl", hash = "sha256:35cdbd478607036fee40273be8ed54a451f5f23121bd9d4be515158f9498f7ad", size = 60634, upload-time = "2025-11-07T00:45:02.087Z" },
-    { url = "https://files.pythonhosted.org/packages/15/d1/b51471c11592ff9c012bd3e2f7334a6ff2f42a7aed2caffcf0bdddc9cb89/wrapt-2.0.1-py3-none-any.whl", hash = "sha256:4d2ce1bf1a48c5277d7969259232b57645aae5686dba1eaeade39442277afbca", size = 44046, upload-time = "2025-11-07T00:45:32.116Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/41/cad1aba93e752f1f9268c77270da3c469883d56e2798e7df6240dcb2287b/wrapt-1.17.3-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ab232e7fdb44cdfbf55fc3afa31bcdb0d8980b9b95c38b6405df2acb672af0e0", size = 53998, upload-time = "2025-08-12T05:51:47.138Z" },
+    { url = "https://files.pythonhosted.org/packages/60/f8/096a7cc13097a1869fe44efe68dace40d2a16ecb853141394047f0780b96/wrapt-1.17.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:9baa544e6acc91130e926e8c802a17f3b16fbea0fd441b5a60f5cf2cc5c3deba", size = 39020, upload-time = "2025-08-12T05:51:35.906Z" },
+    { url = "https://files.pythonhosted.org/packages/33/df/bdf864b8997aab4febb96a9ae5c124f700a5abd9b5e13d2a3214ec4be705/wrapt-1.17.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6b538e31eca1a7ea4605e44f81a48aa24c4632a277431a6ed3f328835901f4fd", size = 39098, upload-time = "2025-08-12T05:51:57.474Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/81/5d931d78d0eb732b95dc3ddaeeb71c8bb572fb01356e9133916cd729ecdd/wrapt-1.17.3-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:042ec3bb8f319c147b1301f2393bc19dba6e176b7da446853406d041c36c7828", size = 88036, upload-time = "2025-08-12T05:52:34.784Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/38/2e1785df03b3d72d34fc6252d91d9d12dc27a5c89caef3335a1bbb8908ca/wrapt-1.17.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3af60380ba0b7b5aeb329bc4e402acd25bd877e98b3727b0135cb5c2efdaefe9", size = 88156, upload-time = "2025-08-12T05:52:13.599Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/8b/48cdb60fe0603e34e05cffda0b2a4adab81fd43718e11111a4b0100fd7c1/wrapt-1.17.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:0b02e424deef65c9f7326d8c19220a2c9040c51dc165cddb732f16198c168396", size = 87102, upload-time = "2025-08-12T05:52:14.56Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/51/d81abca783b58f40a154f1b2c56db1d2d9e0d04fa2d4224e357529f57a57/wrapt-1.17.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:74afa28374a3c3a11b3b5e5fca0ae03bef8450d6aa3ab3a1e2c30e3a75d023dc", size = 87732, upload-time = "2025-08-12T05:52:36.165Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/b1/43b286ca1392a006d5336412d41663eeef1ad57485f3e52c767376ba7e5a/wrapt-1.17.3-cp312-cp312-win32.whl", hash = "sha256:4da9f45279fff3543c371d5ababc57a0384f70be244de7759c85a7f989cb4ebe", size = 36705, upload-time = "2025-08-12T05:53:07.123Z" },
+    { url = "https://files.pythonhosted.org/packages/28/de/49493f962bd3c586ab4b88066e967aa2e0703d6ef2c43aa28cb83bf7b507/wrapt-1.17.3-cp312-cp312-win_amd64.whl", hash = "sha256:e71d5c6ebac14875668a1e90baf2ea0ef5b7ac7918355850c0908ae82bcb297c", size = 38877, upload-time = "2025-08-12T05:53:05.436Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/48/0f7102fe9cb1e8a5a77f80d4f0956d62d97034bbe88d33e94699f99d181d/wrapt-1.17.3-cp312-cp312-win_arm64.whl", hash = "sha256:604d076c55e2fdd4c1c03d06dc1a31b95130010517b5019db15365ec4a405fc6", size = 36885, upload-time = "2025-08-12T05:52:54.367Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/f6/759ece88472157acb55fc195e5b116e06730f1b651b5b314c66291729193/wrapt-1.17.3-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:a47681378a0439215912ef542c45a783484d4dd82bac412b71e59cf9c0e1cea0", size = 54003, upload-time = "2025-08-12T05:51:48.627Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/a9/49940b9dc6d47027dc850c116d79b4155f15c08547d04db0f07121499347/wrapt-1.17.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:54a30837587c6ee3cd1a4d1c2ec5d24e77984d44e2f34547e2323ddb4e22eb77", size = 39025, upload-time = "2025-08-12T05:51:37.156Z" },
+    { url = "https://files.pythonhosted.org/packages/45/35/6a08de0f2c96dcdd7fe464d7420ddb9a7655a6561150e5fc4da9356aeaab/wrapt-1.17.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:16ecf15d6af39246fe33e507105d67e4b81d8f8d2c6598ff7e3ca1b8a37213f7", size = 39108, upload-time = "2025-08-12T05:51:58.425Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/37/6faf15cfa41bf1f3dba80cd3f5ccc6622dfccb660ab26ed79f0178c7497f/wrapt-1.17.3-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:6fd1ad24dc235e4ab88cda009e19bf347aabb975e44fd5c2fb22a3f6e4141277", size = 88072, upload-time = "2025-08-12T05:52:37.53Z" },
+    { url = "https://files.pythonhosted.org/packages/78/f2/efe19ada4a38e4e15b6dff39c3e3f3f73f5decf901f66e6f72fe79623a06/wrapt-1.17.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ed61b7c2d49cee3c027372df5809a59d60cf1b6c2f81ee980a091f3afed6a2d", size = 88214, upload-time = "2025-08-12T05:52:15.886Z" },
+    { url = "https://files.pythonhosted.org/packages/40/90/ca86701e9de1622b16e09689fc24b76f69b06bb0150990f6f4e8b0eeb576/wrapt-1.17.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:423ed5420ad5f5529db9ce89eac09c8a2f97da18eb1c870237e84c5a5c2d60aa", size = 87105, upload-time = "2025-08-12T05:52:17.914Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/e0/d10bd257c9a3e15cbf5523025252cc14d77468e8ed644aafb2d6f54cb95d/wrapt-1.17.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e01375f275f010fcbf7f643b4279896d04e571889b8a5b3f848423d91bf07050", size = 87766, upload-time = "2025-08-12T05:52:39.243Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/cf/7d848740203c7b4b27eb55dbfede11aca974a51c3d894f6cc4b865f42f58/wrapt-1.17.3-cp313-cp313-win32.whl", hash = "sha256:53e5e39ff71b3fc484df8a522c933ea2b7cdd0d5d15ae82e5b23fde87d44cbd8", size = 36711, upload-time = "2025-08-12T05:53:10.074Z" },
+    { url = "https://files.pythonhosted.org/packages/57/54/35a84d0a4d23ea675994104e667ceff49227ce473ba6a59ba2c84f250b74/wrapt-1.17.3-cp313-cp313-win_amd64.whl", hash = "sha256:1f0b2f40cf341ee8cc1a97d51ff50dddb9fcc73241b9143ec74b30fc4f44f6cb", size = 38885, upload-time = "2025-08-12T05:53:08.695Z" },
+    { url = "https://files.pythonhosted.org/packages/01/77/66e54407c59d7b02a3c4e0af3783168fff8e5d61def52cda8728439d86bc/wrapt-1.17.3-cp313-cp313-win_arm64.whl", hash = "sha256:7425ac3c54430f5fc5e7b6f41d41e704db073309acfc09305816bc6a0b26bb16", size = 36896, upload-time = "2025-08-12T05:52:55.34Z" },
+    { url = "https://files.pythonhosted.org/packages/02/a2/cd864b2a14f20d14f4c496fab97802001560f9f41554eef6df201cd7f76c/wrapt-1.17.3-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:cf30f6e3c077c8e6a9a7809c94551203c8843e74ba0c960f4a98cd80d4665d39", size = 54132, upload-time = "2025-08-12T05:51:49.864Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/46/d011725b0c89e853dc44cceb738a307cde5d240d023d6d40a82d1b4e1182/wrapt-1.17.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:e228514a06843cae89621384cfe3a80418f3c04aadf8a3b14e46a7be704e4235", size = 39091, upload-time = "2025-08-12T05:51:38.935Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/9e/3ad852d77c35aae7ddebdbc3b6d35ec8013af7d7dddad0ad911f3d891dae/wrapt-1.17.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:5ea5eb3c0c071862997d6f3e02af1d055f381b1d25b286b9d6644b79db77657c", size = 39172, upload-time = "2025-08-12T05:51:59.365Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/f7/c983d2762bcce2326c317c26a6a1e7016f7eb039c27cdf5c4e30f4160f31/wrapt-1.17.3-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:281262213373b6d5e4bb4353bc36d1ba4084e6d6b5d242863721ef2bf2c2930b", size = 87163, upload-time = "2025-08-12T05:52:40.965Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/0f/f673f75d489c7f22d17fe0193e84b41540d962f75fce579cf6873167c29b/wrapt-1.17.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:dc4a8d2b25efb6681ecacad42fca8859f88092d8732b170de6a5dddd80a1c8fa", size = 87963, upload-time = "2025-08-12T05:52:20.326Z" },
+    { url = "https://files.pythonhosted.org/packages/df/61/515ad6caca68995da2fac7a6af97faab8f78ebe3bf4f761e1b77efbc47b5/wrapt-1.17.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:373342dd05b1d07d752cecbec0c41817231f29f3a89aa8b8843f7b95992ed0c7", size = 86945, upload-time = "2025-08-12T05:52:21.581Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/bd/4e70162ce398462a467bc09e768bee112f1412e563620adc353de9055d33/wrapt-1.17.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:d40770d7c0fd5cbed9d84b2c3f2e156431a12c9a37dc6284060fb4bec0b7ffd4", size = 86857, upload-time = "2025-08-12T05:52:43.043Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/b8/da8560695e9284810b8d3df8a19396a6e40e7518059584a1a394a2b35e0a/wrapt-1.17.3-cp314-cp314-win32.whl", hash = "sha256:fbd3c8319de8e1dc79d346929cd71d523622da527cca14e0c1d257e31c2b8b10", size = 37178, upload-time = "2025-08-12T05:53:12.605Z" },
+    { url = "https://files.pythonhosted.org/packages/db/c8/b71eeb192c440d67a5a0449aaee2310a1a1e8eca41676046f99ed2487e9f/wrapt-1.17.3-cp314-cp314-win_amd64.whl", hash = "sha256:e1a4120ae5705f673727d3253de3ed0e016f7cd78dc463db1b31e2463e1f3cf6", size = 39310, upload-time = "2025-08-12T05:53:11.106Z" },
+    { url = "https://files.pythonhosted.org/packages/45/20/2cda20fd4865fa40f86f6c46ed37a2a8356a7a2fde0773269311f2af56c7/wrapt-1.17.3-cp314-cp314-win_arm64.whl", hash = "sha256:507553480670cab08a800b9463bdb881b2edeed77dc677b0a5915e6106e91a58", size = 37266, upload-time = "2025-08-12T05:52:56.531Z" },
+    { url = "https://files.pythonhosted.org/packages/77/ed/dd5cf21aec36c80443c6f900449260b80e2a65cf963668eaef3b9accce36/wrapt-1.17.3-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:ed7c635ae45cfbc1a7371f708727bf74690daedc49b4dba310590ca0bd28aa8a", size = 56544, upload-time = "2025-08-12T05:51:51.109Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/96/450c651cc753877ad100c7949ab4d2e2ecc4d97157e00fa8f45df682456a/wrapt-1.17.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:249f88ed15503f6492a71f01442abddd73856a0032ae860de6d75ca62eed8067", size = 40283, upload-time = "2025-08-12T05:51:39.912Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/86/2fcad95994d9b572db57632acb6f900695a648c3e063f2cd344b3f5c5a37/wrapt-1.17.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:5a03a38adec8066d5a37bea22f2ba6bbf39fcdefbe2d91419ab864c3fb515454", size = 40366, upload-time = "2025-08-12T05:52:00.693Z" },
+    { url = "https://files.pythonhosted.org/packages/64/0e/f4472f2fdde2d4617975144311f8800ef73677a159be7fe61fa50997d6c0/wrapt-1.17.3-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:5d4478d72eb61c36e5b446e375bbc49ed002430d17cdec3cecb36993398e1a9e", size = 108571, upload-time = "2025-08-12T05:52:44.521Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/01/9b85a99996b0a97c8a17484684f206cbb6ba73c1ce6890ac668bcf3838fb/wrapt-1.17.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:223db574bb38637e8230eb14b185565023ab624474df94d2af18f1cdb625216f", size = 113094, upload-time = "2025-08-12T05:52:22.618Z" },
+    { url = "https://files.pythonhosted.org/packages/25/02/78926c1efddcc7b3aa0bc3d6b33a822f7d898059f7cd9ace8c8318e559ef/wrapt-1.17.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e405adefb53a435f01efa7ccdec012c016b5a1d3f35459990afc39b6be4d5056", size = 110659, upload-time = "2025-08-12T05:52:24.057Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/ee/c414501ad518ac3e6fe184753632fe5e5ecacdcf0effc23f31c1e4f7bfcf/wrapt-1.17.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:88547535b787a6c9ce4086917b6e1d291aa8ed914fdd3a838b3539dc95c12804", size = 106946, upload-time = "2025-08-12T05:52:45.976Z" },
+    { url = "https://files.pythonhosted.org/packages/be/44/a1bd64b723d13bb151d6cc91b986146a1952385e0392a78567e12149c7b4/wrapt-1.17.3-cp314-cp314t-win32.whl", hash = "sha256:41b1d2bc74c2cac6f9074df52b2efbef2b30bdfe5f40cb78f8ca22963bc62977", size = 38717, upload-time = "2025-08-12T05:53:15.214Z" },
+    { url = "https://files.pythonhosted.org/packages/79/d9/7cfd5a312760ac4dd8bf0184a6ee9e43c33e47f3dadc303032ce012b8fa3/wrapt-1.17.3-cp314-cp314t-win_amd64.whl", hash = "sha256:73d496de46cd2cdbdbcce4ae4bcdb4afb6a11234a1df9c085249d55166b95116", size = 41334, upload-time = "2025-08-12T05:53:14.178Z" },
+    { url = "https://files.pythonhosted.org/packages/46/78/10ad9781128ed2f99dbc474f43283b13fea8ba58723e98844367531c18e9/wrapt-1.17.3-cp314-cp314t-win_arm64.whl", hash = "sha256:f38e60678850c42461d4202739f9bf1e3a737c7ad283638251e79cc49effb6b6", size = 38471, upload-time = "2025-08-12T05:52:57.784Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/f6/a933bd70f98e9cf3e08167fc5cd7aaaca49147e48411c0bd5ae701bb2194/wrapt-1.17.3-py3-none-any.whl", hash = "sha256:7171ae35d2c33d326ac19dd8facb1e82e5fd04ef8c6c0e394d7af55a55051c22", size = 23591, upload-time = "2025-08-12T05:53:20.674Z" },
 ]
 
 [[package]]