Embeddings: DB-only boundary

In plain terms: Eigen Mesh stores mathematical search indexes internally but never sends them to AI tools or chat — only human-readable text appears in prompts and tool results.

Status: Enforced in the eigen product codebase. Risk: Critical (ingestion, retrieval, MCP, chat).

Who this is for

Operators auditing data exposure in self-hosted deployments
Integrators reviewing what MCP tools may return to AI clients

Policy

Embedding vectors (1536-dimensional floats for thoughts, entities, temporal events, etc.) are core infrastructure:

Allowed: compute via the embedding gateway, store in Postgres/pgvector, use inside retrieval and consolidation (distance queries, internal pipelines).
Forbidden: return vectors from MCP tools, HTTP tool-shaped APIs, chat/agent payloads, or any LLM chat completion request; log full vectors or long embedding inputs.

Text fields (normalizedText, snippets, scores) are fine in tools and LLM prompts. Vectors are not.

Why

Vectors are large (~6k+ tokens each if serialized), leak no useful semantics to chat models, and blow context windows.
User trust: memory content in prompts should be human-readable text, not raw numeric embeddings.

Enforcement (defense in depth)

The eigen product applies multiple layers:

Layer	Role
Query shape	Tool-facing reads exclude `embedding` columns
MCP tools	Sanitize every tool return before JSON serialization
Agent loop	Sanitize after each tool; compact results for follow-up turns
Chat gateway	Strip vectors immediately before LLM requests
Shared stripper	Recursively remove vector field names and 1536-element numeric arrays
Logs	No vector previews in console output

Retrieval and compose-answer

searchThoughts / retrieve_thoughts returns scores and text, not stored thought embeddings.
composeAnswer and in-app chat build LLM prompts from text, category, scores, and dates — never from embedding columns.
Query embeddings are created in-process for SQL distance only; they are not attached to tool results.

Intentional exception

The graph embedding map UI (GET /api/embeddings/snapshot) returns vectors for authorized in-browser visualization only — not MCP, not chat LLM.

For integrators

When building on MCP or REST:

Never expect or request embedding arrays in tool results — they are stripped by design.
Use retrieve_thoughts text fields and scores for context assembly.
See MCP tools reference.

For contributors

Implementation file paths and PR review checklist live in the eigen repository's contributor docs and .cursor/rules/no-embeddings-in-llm.mdc.

Domain entry points: Ingestion, Retrieval.

Troubleshooting

Embedding-related issues are rare for end users. See Troubleshooting for broader MCP and retrieval problems.

Next steps

MCP tools reference — allowed tool response fields
How memory works — retrieval pipeline overview