# garden.engram.defs

> Published by [hailey.at](https://lexicon.garden/identity/did:plc:oisofpd7lj26yvgiivf3lxsi)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:oisofpd7lj26yvgiivf3lxsi/garden.engram.defs)
- [Documentation](https://lexicon.garden/lexicon/did:plc:oisofpd7lj26yvgiivf3lxsi/garden.engram.defs/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:oisofpd7lj26yvgiivf3lxsi/garden.engram.defs/examples)

## Definitions

### `garden.engram.defs#byteSlice`

**Type**: `object`

A UTF-8 byte range in a snippet's text, like a rich-text facet's index.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `byteEnd` | `integer` | Yes |  |
| `byteStart` | `integer` | Yes |  |

### `garden.engram.defs#embedding`

**Type**: `object`

A vector for a memory, computed by its author from the memory's text and tags (with the space's document prefix).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `dims` | `integer` | Yes |  |
| `encoding` | `string` | Yes | f16le: little-endian IEEE half precision, 2 bytes per dimension. |
| `model` | `string` | Yes |  |
| `modelDigest` | `string` | Yes |  |
| `vector` | `bytes` | Yes |  |

### `garden.engram.defs#keywordMatch`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `rank` | `integer` | Yes | The result's rank by keyword score among the results. |
| `score` | `integer` | Yes | The BM25 keyword score × 100. |
| `terms` | `array` | Yes | The query terms the memory contains: per query word, its exact form if present, else its stem, else an identifier's parts. |

### `garden.engram.defs#matchView`

**Type**: `object`

Why a search result matched.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `fusion` | `string` | No | Hybrid results: how the vector and keyword scores were combined. |
| `keyword` | `ref` → `#keywordMatch` | No | Present when any query term occurs in the memory. |
| `snippet` | `ref` → `#snippetView` | No |  |
| `vector` | `ref` → `#vectorMatch` | No |  |

### `garden.engram.defs#memoryView`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `author` | `string` (did) | Yes |  |
| `cid` | `string` (cid) | Yes |  |
| `createdAt` | `string` (datetime) | Yes |  |
| `indexedAt` | `string` (datetime) | Yes |  |
| `match` | `ref` → `#matchView` | No | Hybrid and keyword search results only: why the memory matched. |
| `similarity` | `integer` | No | Search results only: cosine similarity to the query, scaled to 0-1000. Absent from keyword-only results. |
| `source` | `string` | No |  |
| `tags` | `array` | Yes |  |
| `text` | `string` | Yes |  |
| `uri` | `string` | Yes | The memory's space record URI: at://{authority}/space/{spaceType}/{skey}/{author}/garden.engram.memory/{rkey}. |

### `garden.engram.defs#model`

**Type**: `object`

An embedding model, identified exactly. Vectors are comparable only when all three fields match.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `dims` | `integer` | Yes |  |
| `model` | `string` | Yes | The model's name, such as nomic-embed-text. |
| `modelDigest` | `string` | Yes | Pins the exact model build, such as Ollama's sha256 digest of the model. A name can point to different weights over time. |

### `garden.engram.defs#snippetView`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | `string` | Yes |  |
| `highlights` | `array` | Yes |  |
| `text` | `string` | Yes | Up to about 200 characters of the field around the matches, with … where cut. |

### `garden.engram.defs#termMatch`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | `string` | Yes |  |
| `kind` | `string` | Yes |  |
| `term` | `string` | Yes | The normalized term; stems start with ~. |

### `garden.engram.defs#vectorMatch`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `rank` | `integer` | Yes | The result's rank by similarity among the results. |
| `similarity` | `integer` | Yes | Cosine similarity, scaled to 0-1000. |

## Raw Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "byteSlice": {
      "description": "A UTF-8 byte range in a snippet's text, like a rich-text facet's index.",
      "properties": {
        "byteEnd": {
          "minimum": 0,
          "type": "integer"
        },
        "byteStart": {
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "byteStart",
        "byteEnd"
      ],
      "type": "object"
    },
    "embedding": {
      "description": "A vector for a memory, computed by its author from the memory's text and tags (with the space's document prefix).",
      "properties": {
        "dims": {
          "maximum": 16000,
          "minimum": 1,
          "type": "integer"
        },
        "encoding": {
          "description": "f16le: little-endian IEEE half precision, 2 bytes per dimension.",
          "knownValues": [
            "f16le"
          ],
          "type": "string"
        },
        "model": {
          "maxLength": 256,
          "type": "string"
        },
        "modelDigest": {
          "maxLength": 256,
          "type": "string"
        },
        "vector": {
          "maxLength": 32000,
          "type": "bytes"
        }
      },
      "required": [
        "model",
        "modelDigest",
        "dims",
        "encoding",
        "vector"
      ],
      "type": "object"
    },
    "keywordMatch": {
      "properties": {
        "rank": {
          "description": "The result's rank by keyword score among the results.",
          "minimum": 1,
          "type": "integer"
        },
        "score": {
          "description": "The BM25 keyword score × 100.",
          "minimum": 0,
          "type": "integer"
        },
        "terms": {
          "description": "The query terms the memory contains: per query word, its exact form if present, else its stem, else an identifier's parts.",
          "items": {
            "ref": "#termMatch",
            "type": "ref"
          },
          "type": "array"
        }
      },
      "required": [
        "rank",
        "score",
        "terms"
      ],
      "type": "object"
    },
    "matchView": {
      "description": "Why a search result matched.",
      "properties": {
        "fusion": {
          "description": "Hybrid results: how the vector and keyword scores were combined.",
          "knownValues": [
            "convex",
            "rrf"
          ],
          "type": "string"
        },
        "keyword": {
          "description": "Present when any query term occurs in the memory.",
          "ref": "#keywordMatch",
          "type": "ref"
        },
        "snippet": {
          "ref": "#snippetView",
          "type": "ref"
        },
        "vector": {
          "ref": "#vectorMatch",
          "type": "ref"
        }
      },
      "type": "object"
    },
    "memoryView": {
      "properties": {
        "author": {
          "format": "did",
          "type": "string"
        },
        "cid": {
          "format": "cid",
          "type": "string"
        },
        "createdAt": {
          "format": "datetime",
          "type": "string"
        },
        "indexedAt": {
          "format": "datetime",
          "type": "string"
        },
        "match": {
          "description": "Hybrid and keyword search results only: why the memory matched.",
          "ref": "#matchView",
          "type": "ref"
        },
        "similarity": {
          "description": "Search results only: cosine similarity to the query, scaled to 0-1000. Absent from keyword-only results.",
          "maximum": 1000,
          "minimum": 0,
          "type": "integer"
        },
        "source": {
          "type": "string"
        },
        "tags": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "text": {
          "type": "string"
        },
        "uri": {
          "description": "The memory's space record URI: at://{authority}/space/{spaceType}/{skey}/{author}/garden.engram.memory/{rkey}.",
          "type": "string"
        }
      },
      "required": [
        "uri",
        "cid",
        "author",
        "text",
        "tags",
        "createdAt",
        "indexedAt"
      ],
      "type": "object"
    },
    "model": {
      "description": "An embedding model, identified exactly. Vectors are comparable only when all three fields match.",
      "properties": {
        "dims": {
          "maximum": 16000,
          "minimum": 1,
          "type": "integer"
        },
        "model": {
          "description": "The model's name, such as nomic-embed-text.",
          "maxLength": 256,
          "type": "string"
        },
        "modelDigest": {
          "description": "Pins the exact model build, such as Ollama's sha256 digest of the model. A name can point to different weights over time.",
          "maxLength": 256,
          "type": "string"
        }
      },
      "required": [
        "model",
        "modelDigest",
        "dims"
      ],
      "type": "object"
    },
    "snippetView": {
      "properties": {
        "field": {
          "knownValues": [
            "text",
            "tags",
            "source"
          ],
          "type": "string"
        },
        "highlights": {
          "items": {
            "ref": "#byteSlice",
            "type": "ref"
          },
          "type": "array"
        },
        "text": {
          "description": "Up to about 200 characters of the field around the matches, with … where cut.",
          "type": "string"
        }
      },
      "required": [
        "field",
        "text",
        "highlights"
      ],
      "type": "object"
    },
    "termMatch": {
      "properties": {
        "field": {
          "knownValues": [
            "text",
            "tags",
            "source"
          ],
          "type": "string"
        },
        "kind": {
          "knownValues": [
            "exact",
            "stem",
            "part"
          ],
          "type": "string"
        },
        "term": {
          "description": "The normalized term; stems start with ~.",
          "type": "string"
        }
      },
      "required": [
        "term",
        "kind",
        "field"
      ],
      "type": "object"
    },
    "vectorMatch": {
      "properties": {
        "rank": {
          "description": "The result's rank by similarity among the results.",
          "minimum": 1,
          "type": "integer"
        },
        "similarity": {
          "description": "Cosine similarity, scaled to 0-1000.",
          "maximum": 1000,
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "rank",
        "similarity"
      ],
      "type": "object"
    }
  },
  "id": "garden.engram.defs",
  "lexicon": 1
}
```