feat(core): add semantic embedding text prefixes

[lastguru-net]

Summary

Adds optional role-specific literal text prefixes for semantic embeddings:

• semantic_embedding_document_prefix
• semantic_embedding_query_prefix

These prefixes are prepended to the actual text sent to the embedding provider:

• document prefix for indexed chunks during sync/reindex
• query prefix for vector and hybrid search queries

Fixes #1008.

Why

Some embedding models require role-specific text prefixes as part of the input string, not as API parameters.

Examples include models where the recommended input format is something like:

• documents: title: none | text: ...
• queries: task: search result | query: ...

Basic Memory already supports LiteLLM input_type settings, but that only helps providers that understand an API-level role parameter. OpenAI-compatible endpoints such as TEI just receive the input strings, so prefix-sensitive models cannot currently be used in their recommended form without a proxy or local patch.
Without this, retrieval quality evaluation is misleading: a model can look worse than it really is because documents and queries are embedded without the format it was trained/evaluated with.

Implementation

• Adds document/query prefix config fields.
• Wraps embedding providers with a generic prefixing provider.
• Works across fastembed, openai, and litellm.
• Empty or unset prefixes preserve current behavior.
• Includes prefixes in the provider cache key.
• Includes prefixes in stored vector identity, so changing either prefix invalidates existing embeddings and requires reindexing.
• Exposes prefix-enabled status in runtime/project status surfaces.
• Documents the difference between LiteLLM input_type and literal text prefixes.

Validation

• 201 passed focused tests
• Ruff format/check on touched Python files
• ty check src tests test-int
• git diff --check

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7f7198d58a

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[lastguru-net]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: 0818b8d7da

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[phernandez]

Thanks for the contribution — I rebased this onto current main and completed the maintainer hardening directly on the branch. The feature still applies independent document/query text prefixes and now also keeps raw prefix text out of process cache keys and persisted vector identities by using stable SHA-256 digests. I replaced the speculative identity lookup with a narrow provider capability and expanded coverage for prefix application, invalidation, unset-vs-literal values, cache privacy, diagnostics, and SQLite resync behavior.\n\nValidation on the final local head: 3,754 unit tests passed (33 skipped), 230 focused semantic/config/status tests passed, and Ruff + ty passed.

[phernandez]

@codex review

[phernandez]

@codex recheck

[chatgpt-codex-connector]

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

Unknown error

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[phernandez]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: 5aebf7df9f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".