Search Artifacts

Use the unified search route to find relevant current Artifact heads in one Scope. Each result contains the exact family, artifact_id, and revision, complete family-specific content, and lineage. Search does not enumerate every Artifact or search across Scopes. Use Manage Artifacts for lists and exact historical reads; use Prepare context text when an Agent needs bounded context instead of complete content.

Send a search request

The caller needs scope.read access. Put the Scope and Family in the path, and the search controls in the body. Identity, access, and audit context come from server authentication and cannot be supplied in the request body:

POST /v1/scopes/project-a/artifacts/experience/search
Content-Type: application/json

{
  "query": "release rollback",
  "limit": 5,
  "include_scores": true
}

Use the Server URL and credentials from your trusted environment. Include Authorization: Bearer <token> when Access is enabled. The response is {"results": [...]}; an empty results array is a successful search with no admitted result. Results retain their actual content fields and exact revision lineage.

Family support

The built-in deployment currently exposes these capabilities through this route:

Sources are evidence and Tags are metadata; neither is an Artifact Family for this route. The deployment must have the selected Family's retrieval index enabled. Topic and Atomic vector and hybrid modes also require a compatible configured Embedding model and index Profile. See Configure vector search for deployment settings.

Common controls and limits

Omit optional fields to use their defaults. Explicit null, unknown fields, numeric strings, and booleans in numeric fields are rejected. limit must be an integer; include_scores must be a JSON boolean. Request rerank and the weighted_score fusion method are unsupported. Experience and Skill reject fusion entirely.

Thresholds are applied after admission and score calculation, before the final limit. The search does not add lower scoring candidates to fill a result after min_score removes hits. Enabling scores changes only response metadata; it does not change candidate admission, identities, ordering, or thresholds.

Shared word analysis

Chinese text is segmented into words; Latin words and identifiers remain whole. Unquoted queries omit common English and Chinese stopwords while retaining negations. Quote a stopword to search for it; quotations do not request phrase matching.

Record formats remain v1. Before upgrading, stop existing Server and Worker processes. The first startup after a document analyzer upgrade updates searchable text without changing record content, history or vectors. This startup can take longer as stored data grows.

Experience and Skill text search

Both Families search one text channel. Their admission fields are:

Let n be the number of distinct analyzed query terms. A query with at most two terms requires one matching term. Longer queries require at least max(lexical_min_matched_terms, ceil(lexical_coverage × n)) matching terms. This admission check precedes scoring and truncation. Unapproved or inactive heads cannot enter the result.

Their normalized score is relevance / (1 + relevance), where relevance is the negated SQLite BM25 raw score or the OceanBase MATCH raw score. Both backends produce scores in [0, 1], but their scales differ. Choose min_score from observed results for your backend and workload; there is no shared recommended threshold across backends.

Topic Memory controls

Topic has four named channels:

Text searches title/summary and detail separately. Vector searches use the deployment's Embedding Profile. Text and hybrid queries allow at most 64 distinct analyzed terms; vector-only queries use the 8192-character limit.

Topic supports the two lexical admission fields above and admission.min_semantic_similarity, a finite number in [-1, 1] with default 0.3. Each lexical channel applies the matching-term rule independently. Each vector channel requires clip(1 - distance² / 2, -1, 1) >= min_semantic_similarity, using the normalized vectors' L2 distance. A failure in one channel removes that channel's contribution, while another admitted channel may still retain the topic.

Topic combines admitted rankings with RRF. Omitted fusion uses rrf, rank constant 60, and weight 1 per enabled channel. The normalized RRF score is described in Fusion algorithms and parameters.

POST /v1/scopes/project-a/artifacts/topic-memory/search
Content-Type: application/json

{
  "query": "release rollback",
  "mode": "hybrid",
  "limit": 5,
  "admission": {"lexical_coverage": 0.5},
  "fusion": {
    "method": "rrf",
    "params": {
      "rank_constant": 60,
      "weights": {"topic_fts": 2, "detail_vector": 0.5}
    }
  },
  "include_scores": true
}

Parameter combinations are validated even when the Scope contains no topics:

• text rejects an explicitly supplied semantic admission field and any vector weight key, including weight 0.
• vector rejects explicitly supplied lexical admission fields and any FTS weight key, including weight 0.
• A weight key must name an enabled channel. Unknown channels and an enabled set with total weight 0 are rejected.
• Explicit vector or hybrid, an explicit semantic threshold, or any vector weight key requires vector capability. An explicitly supplied value equal to its default still carries this requirement.

With omitted mode, Topic uses hybrid when Embedding is configured and text otherwise. If the default hybrid request has no explicit vector requirement, a temporarily unavailable or timed-out Embedding call may fall back to text, provided the FTS channels have positive total weight. Explicit vector/hybrid requests and explicit vector requirements never fall back. If both FTS weights are 0, an Embedding failure remains a service failure. Invalid vectors, incompatible Profiles, and storage failures do not trigger text fallback.

Atomic Memory controls

Atomic search requires scope.read. Sharing an individual Artifact permits exact reads and history access, but does not grant Scope search. The retired memory Family is not a search fallback.

Atomic searches active current heads through text, vector, or hybrid. Omitted mode always selects text, including deployments with Embedding. Vector and hybrid require a matching enabled index Profile and configured Embedding model; these requests do not fall back to text. Capability and parameter checks run before an empty Scope can return no results.

Atomic uses channel names text and vector. It applies the lexical admission rule above to text and the same L2-derived semantic rule as Topic to vectors. The admission defaults are lexical coverage 0.25, minimum matched terms 2, and semantic similarity 0.3. Explicit semantic admission is invalid in text mode; explicit lexical admission is invalid in vector mode. Weight keys must belong to enabled channels, even when their weight is 0.

Scope read is authorized before retrieval. Atomic filters and active-state eligibility apply before candidate ranking and truncation:

Tags use the existing NFC and case-folded matching rules. Migrated entry tags belong to the Atomic Artifact target; search them with filters.tags. See Manage Artifact tags.

POST /v1/scopes/project-a/artifacts/atomic-memory/search
Content-Type: application/json

{
  "query": "release rollback",
  "mode": "hybrid",
  "limit": 10,
  "filters": {"kind": "decision", "tags": ["release"], "tag_match": "all"},
  "fusion": {"method": "rrf", "params": {"rank_constant": 60, "weights": {"text": 2}}},
  "include_scores": true
}

Atomic uses normalized RRF even in a single-channel mode. min_score filters the fused retrieval score before deployment-configured reranking and final selection. A configured reranker remains active and can change result order; it does not rewrite retrieval or raw channel scores. The request cannot enable, disable, or configure reranking. Results contain full immutable Artifact content and lineage. Read current lifecycle and state version through the Atomic Memory interfaces.

Read the scores

With include_scores: true, each result includes a scores object. This example shows only that field:

{
  "scores": {
    "retrieval": 0.5,
    "channels": {
      "topic_fts": {
        "raw": -0.000004,
        "metric": "sqlite_bm25",
        "higher_is_better": false
      }
    }
  }
}

retrieval is the normalized score in [0, 1] used for min_score and ranking before any configured Atomic reranking. channels contains the actual raw scores of channels that admitted this result:

Experience and Skill use text; Atomic uses text and vector; Topic uses the four names above. Missing channels are omitted, with no fabricated zero. An admitted zero-weight channel can still appear in metadata when another channel selects the same Artifact. Topic detail raw scores belong to the representative detail chunk selected by that channel.

Raw values are backend and query dependent; they are not a universal similarity scale across queries or backends. Topic and Atomic channel raw values are FTS scores or vector distances, not RRF contributions. Scores belong to this search response and do not alter persisted Artifact content or lineage. With include_scores: false, scores is omitted.

Failures and existing interfaces

An unknown Family returns 404. A known Family without unified search, an unavailable configured search capability, or an unsupported parameter returns 422. Invalid requests report the parameter path; changing the limit or using an empty Scope does not bypass validation. Model timeout/unavailability returns a service error when fallback is not permitted (503). Implementation and storage failures remain failures, rather than successful empty results.

Unified search preserves the dedicated Atomic and Topic search behavior, Skill Library search, and existing SDK/internal Experience recall. Legacy Memory collections are removed from public Artifact storage by the offline migration. The retained POST /v1/memory/search route translates requests into Atomic Memory calls and returns Atomic records; it does not search old collections. The retained routes and rejected operations are described in Atomic Memory compatibility. In particular, POST /v1/topic-memory/search still chooses the deployment default and returns summary hits with its legacy score scale of 0–100; it does not expose these advanced controls. The unified Topic route returns complete Artifact content and uses retrieval scores in [0, 1]. See Use Topic Memory for the dedicated summary search and exact detail-read workflow.