EmbeddedSemantics

First-party machine-intelligence contract

Connect through MCP or the API, then interpret every outcome correctly.

Desktop agents and local models use Embedded Semantics at durable semantic boundaries such as memory, APIs, workflow routing, cross-language handoffs, and audit evidence. Accept a ConceptCode only from an explicit resolved response, preserve abstention, and keep semantic identity separate from permission to act.

Connect through MCP Use the direct API

MCP connection quickstart

Give an agent a standard tool-and-resource connection.

Point a current MCP client at one remote Streamable HTTP endpoint. Start with server/discover, list the fixed catalog, and call the same governed resolver used by the direct API. The endpoint is stateless and read-only: it creates no protocol session, mutates no registry state, and grants no action authority.

Open complete MCP directions →
  1. 01
    Verify identity and the discovery receipt

    Check the deployment identity against an independently approved digest, then fetch the deterministic discovery receipt. Confirm its exact ten-route inventory and routeInventorySha256 before selecting the MCP endpoint.

  2. 02
    Discover capabilities

    POST server/discover with the required request metadata and mirrored routing headers. Confirm the fixed read-only catalog includes the same discovery receipt and deployment identity.

  3. 03
    List or call

    Use tools/list, then call embedded_semantics.resolve_expression or embedded_semantics.get_concept.

  4. 04
    Apply the same fail-closed rule

    Accept a code only on explicit resolution. Unknown, ambiguity, tool errors, and HTTP 429 assign no ConceptCode; honor Retry-After before any bounded retry.

Direct API connection quickstart

Use two plain HTTPS requests when MCP discovery is unnecessary.

Start with the stateless bootstrap endpoint. It returns the canonical origin, current registry readiness, the one supported resolver URL, and the exact fail-closed decision rule. It does not register the client, create a session, or accept credentials.

Open connection JSON →
  1. 01
    Verify identity, then fetch the bootstrap

    Confirm https://embeddedsemantics.com/.well-known/embedded-semantics-deployment.json against the approved package and closure digest, then send a body-free GET to discover the canonical resolver contract.

  2. 02
    Send one expression

    POST only expression and an optional known BCP 47 language tag to the returned resolver URL.

  3. 03
    Interpret the semantic outcome

    Accept identity only after an explicit resolved response with non-empty code and registry version. Every other outcome is no assignment.

  4. 04
    Authorize separately

    A ConceptCode identifies governed meaning. Your own policy still decides whether any memory write, route, tool call, or other side effect is allowed.

MVP connection bootstrap
Stateless · no auth · no session 
GET https://embeddedsemantics.com/api/v1/agent/connect

No request body. No agent name, device ID, token, prompt, conversation, or private context.

Then resolve one expression 
POST https://embeddedsemantics.com/api/v1/resolve
Content-Type: application/json

{
  "expression": "stable concept identity",
  "language": "en"
}
Connection schema OpenAPI contract Tool descriptor
What direct API “connect” means

A desktop agent can verify the service and obtain the current request contract over ordinary HTTPS. There is no WebSocket, background channel, account registration, remote tool control, or persistent connection state.

Local desktop foundation

Prove the client offline before enabling HTTPS.

The root deployment package includes a dependency-free loopback prototype. It consumes one Integration Studio kit unchanged, replays the same six fixtures with zero network calls, and makes the live bootstrap a separate user-controlled step.

Open setup directions Inspect the source kit
From the extracted package root 
python -m desktop_app --open-browser
  • Python standard library for the local shell
  • Loopback bind only: 127.0.0.1
  • In-memory state; restart returns to offline mode
  • No hosted provider, account, token, or background channel

Live readiness

Inspect the deployed state before relying on it.

Full registry status →
Positive exact resolution possible No Requires a published Concept and reviewed exact-expression evidence.
Published Concepts 0 Stable public registry identities currently deployed.
Reviewed exact expressions 0 Production-authoritative lookup evidence currently deployed.
Resolver authority Registry first reviewed_exact_registry_first
Arbitrary query: not_production_active

Public bundle: embedded-semantics.public-registry-prerelease · complete: no · SHA-256: 30811e375cdfc7c92828270aedd9bfde96dc92cf190096ad6bc6772de2fc995f

The deployed public corpus cannot currently return a positive exact resolution.

The endpoint may still process requests and return explicit abstention. An agent must not treat an empty or incomplete deployment as permission to infer or manufacture a ConceptCode.

Architecture

The agent is a client, not the authority.

A desktop application, local LLM, or local agent sends minimal HTTPS JSON to Embedded Semantics. The published registry record remains authority. The client does not need to host the site, duplicate the registry, run an embedding model, or add an external execution provider merely to call the API.

Where it benefits an agent

Use semantic resolution where the result has a durable consumer.

Full adoption guide →
01

Multilingual agent memory

Store the original wording beside a resolved ConceptCode and registryVersion so later systems can refer to the same reviewed meaning without erasing the user's language.

Place it: At the durable-memory write boundary, not on every conversational turn.
02

Agent and workflow routing

A governed ConceptCode can become a stable semantic input to a separately authorized routing policy.

Place it: Immediately before a semantic routing decision whose policy already recognizes published codes.
03

API, event, and record interoperability

Attach an exact ConceptCode and registryVersion to a record or event so recipients can inspect the same definition while retaining their own display language.

Place it: At an API, event, or persistence boundary where semantic metadata is part of the contract.
04

Human clarification and safer assistance

The resolver's unknown and ambiguous outcomes give the interface a principled reason to preserve uncertainty, ask a targeted question, or continue without semantic identity.

Place it: At a decision point where choosing the wrong meaning would materially change the next step.
Placement rule: resolve at durable memory, API/event, routing, clarification, or audit boundaries—not on every conversational turn. Preserve the original expression beside any resolved code.

Call the resolver when

  • A workflow needs a stable governed ConceptCode for one human-language expression.
  • The caller can preserve an explicit unknown or ambiguous result without guessing.
  • The caller needs to inspect a published Concept record or current resolver readiness.

Do not call it when

  • The task is ordinary question answering, summarization, translation, or writing and no ConceptCode is required.
  • The caller is seeking permission, authorization, or approval to execute an action.
  • The caller intends to select a likely code after the resolver abstains.
  • The caller only needs topic similarity, search ranking, or an unconstrained model classification.

Required procedure

Eight steps, no hidden inference.

01

Determine whether the workflow actually requires a stable ConceptCode; otherwise do not call the resolver.

02

Before integration, select one canonical recipe and run the dependency-free local readiness self-test.

03

Fetch capabilities or status at session start and after a deployment, bundle, or registry-version change.

04

Send only the exact expression to resolve; include language only when a valid BCP 47 tag is known.

05

Treat HTTP success as transport success only. Inspect data.status, data.reason, and error.

06

Accept identity only from data.concept.code on a resolved response; preserve the code and registryVersion exactly.

07

On every abstention, assign no ConceptCode; preserve unknown or ambiguous and never choose from candidates.

08

Apply a separate authorization policy before any tool or action; semantic identity alone authorizes nothing.

Minimal request

Send only the expression.

Include a valid BCP 47 language tag only when known. Do not send credentials, hidden prompts, unrelated conversation, or private context.

POST /api/v1/resolve
Content-Type: application/json

{
  "expression": "stable concept identity",
  "language": "en"
}

Decision

Inspect semantic status.

HTTP 200 means the request was processed. It does not mean a ConceptCode was assigned.

if data.status == "resolved"
   and data.concept.code is a non-empty string:
    accept the exact returned code
    preserve registryVersion
else:
    assign no ConceptCode

Outcome handling

Abstention is a complete answer.

resolved

Use data.concept.code exactly as returned and retain data.concept.registryVersion.

unknown_expression

No governed exact identity is available. Return unknown. Do not guess from labels, candidates, embeddings, or model intuition.

ambiguous_expression

More than one governed exact identity is possible. Ask for clarification or preserve ambiguity. Do not select silently.

Input or service error

Repair only the stated request defect or report the service problem. Never replace an error with an inferred semantic result.

The agent must

  • Preserve the user's original expression in the client context.
  • Send only the minimum text necessary for semantic identity resolution.
  • Preserve ConceptCode spelling, punctuation, namespace, and case exactly as returned.
  • Preserve explicit unknown and ambiguous outcomes.
  • Treat registryVersion as part of the evidence needed to interpret cached records.
  • Use status/capabilities to distinguish resolver implementation from deployed corpus availability.
  • Run the local readiness self-test before wiring a real downstream side effect.
  • Apply action authorization independently from semantic resolution.

The agent must not

  • Do not construct a ConceptCode from labels, definitions, examples, URLs, embeddings, or model output.
  • Do not treat candidates, similarity scores, confidence, or model metadata as semantic authority.
  • Do not silently translate, normalize, shorten, alias, or repair a returned ConceptCode.
  • Do not convert unknown_expression into a guessed resolution.
  • Do not convert ambiguous_expression into a selected resolution without new governed evidence.
  • Do not send credentials, hidden prompts, or unrelated private context to the resolver.
  • Do not treat this API as authorization to perform an action; semantic identity and authorization are separate.

Local-model prompt

Give the model an explicit operating policy.

Use Embedded Semantics only when a stable ConceptCode is required.
Place resolution at a durable memory, API/event, routing,
clarification, or audit boundary—not on every conversation turn.
Before connecting a real side effect, select one recipe and run
the six-fixture local readiness self-test.

Send only the expression and an optional known language tag.
Preserve the original expression beside any resolved code.
Accept identity only when:
data.status == "resolved"
and data.concept.code is a non-empty string.

Every abstained result means no ConceptCode assignment.
Preserve unknown_expression and ambiguous_expression.
Never construct a code from labels, candidates, scores,
embeddings, or your own model output.
Semantic identity does not authorize an action.
Copy the full operating instructions → Inspect the Integration Studio contract → Inspect an example kit manifest → Open the API contract → Verify the deployment identity →