EngramEngramDocs

Protocol Reference

The Engram wire protocol — synapse types, CID specification, scoring formulas, and network constants.

Synapse types

Engram uses two Bittensor synapse types for neuron communication:

IngestSynapseValidator → Miner

Carry text and metadata to the miner for embedding and storage.

textstrText to embed (max 8192 chars)
metadatadictKey-value metadata (max 4 KB)
→ cidstrAssigned content identifier
→ errorstr | NoneError message if failed
QuerySynapseValidator → Miner

Carry a query text and top_k. Miner returns ranked results.

query_textstrNatural language query
top_kintMax results (1–100)
→ resultslist[dict]Ranked {cid, score, metadata}
→ errorstr | NoneError message if failed

CID specification

CIDs are deterministically derived from the embedding vector using SHA-256:

python
# CID derivation (simplified)
import hashlib
def derive_cid(embedding: list[float]) -> str:
raw = b"".join(struct.pack(", x) for x in embedding)
digest = hashlib.sha256(raw).hexdigest()
return f"v1::{digest[:32]}"
# Example
cid = "v1::a3f2b1c4d5e6f7a8b9c0d1e2f3a4b5c6"
Note
The same text always produces the same CID regardless of which miner stores it. This is the core content-addressing guarantee.

Scoring formulas

python
# Composite score (computed by validator, per miner)
composite_score = (
0.50 * recall_at_10 # fraction of challenge vectors correctly returned
+ 0.30 * latency_score # normalized inverse latency
+ 0.20 * proof_success_rate # HMAC challenges passed / total
)
# Latency score — 1.0 at ≤100ms, 0.0 at ≥500ms
latency_score = max(0.0, 1.0 - (latency_ms - 100) / 400)
# Miners below 50% proof success rate → weight = 0
if proof_success_rate < 0.50:
composite_score = 0.0
# Weights are proportional to normalized scores
weights = softmax(composite_scores)

Constants

ConstantValueDescription
NETUID42Subnet UID on testnet
EMBEDDING_DIM1536Vector dimension (text-embedding-3-small)
MAX_TEXT_LENGTH8192Max characters per ingest
REPLICATION_FACTOR3Target copies across miners
SCORING_INTERVAL120sTime between scoring rounds
WEIGHT_INTERVAL600sTime between on-chain weight updates
CHALLENGE_SAMPLE_SIZE10CIDs challenged per miner per round
MIN_PROOF_RATE0.50Proof success rate floor
MIN_STAKE_TAO0.001 τMinimum stake to pass stake check
RATE_LIMIT_RPM60Max requests per minute per hotkey
CID_VERSION"v1"Current CID scheme version
engram docs · v0.1edit on github →