### Quick start server setup

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/README.md

Initialize a database, generate an access token, and start the server.

```bash
yantrikdb db --data-dir ./data create default
yantrikdb token --data-dir ./data create --db default
yantrikdb serve --data-dir ./data
# Wire protocol on :7437, HTTP on :7438
```

--------------------------------

### Download and Setup YantrikDB Server

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Commands to download the YantrikDB binaries, set up a database directory, generate an access token, and start the server.

```bash
# Download
wget https://github.com/yantrikos/yantrikdb-server/releases/latest/download/yantrikdb-linux-amd64
chmod +x yantrikdb-linux-amd64
mv yantrikdb-linux-amd64 /usr/local/bin/yantrikdb

wget https://github.com/yantrikos/yantrikdb-server/releases/latest/download/yql-linux-amd64
chmod +x yql-linux-amd64
mv yql-linux-amd64 /usr/local/bin/yql

# Setup
yantrikdb db --data-dir ./data create default
TOKEN=$(yantrikdb token --data-dir ./data create --db default | grep ^ydb_)
echo "$TOKEN" > token.txt

# Run
yantrikdb serve --data-dir ./data
# Wire protocol on :7437, HTTP on :7438
```

--------------------------------

### Install YantrikDB library

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/README.md

Installation commands for Python and Rust environments.

```bash
pip install yantrikdb
# or
cargo add yantrikdb
```

--------------------------------

### Install yantrikdb-witness via Cargo

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-witness/README.md

Use the cargo package manager to install the witness daemon.

```bash
cargo install yantrikdb-witness
```

--------------------------------

### Install YQL via Cargo

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yql/README.md

Install the YQL CLI tool using the Rust package manager.

```bash
cargo install yql
```

--------------------------------

### Install yantrikdb-server via Cargo

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/README.md

Install the server directly using the Rust package manager.

```bash
cargo install yantrikdb-server
```

--------------------------------

### YQL Interactive Session Example

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yql/README.md

An example session demonstrating memory storage, semantic recall, graph relationship creation, and meta-commands.

```text
yql connected to http://localhost:7438
type \h for help, \q to exit

yantrikdb> remember "Alice leads engineering at Acme" importance=0.9 domain=work
✓ stored: 019d623a-3d70-712e-9315-e1da5ee41114

yantrikdb> recall who leads engineering top=5
+---+-------+---------------------------------+--------+--------------------------------+
| # | score | text                            | domain | why                            |
+---+-------+---------------------------------+--------+--------------------------------+
| 1 | 1.41  | Alice leads engineering at Acme | work   | semantically similar (0.54)... |
+---+-------+---------------------------------+--------+--------------------------------+
(1 rows)

yantrikdb> relate Alice -> Acme as works_at
✓ edge: 019d623a-41cf-71a2 (Alice -[works_at]-> Acme)

yantrikdb> \stats
yantrikdb> \cluster
yantrikdb> \q
```

--------------------------------

### CLI Commands

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/DESIGN.md

Common CLI commands for starting the server, managing databases, and handling data exports/imports.

```bash
yantrikdb serve                          # Start server
yantrikdb serve --config ./yantrikdb.toml
yantrikdb db create <name>               # Create database
yantrikdb db list                        # List databases
yantrikdb token create --db <name>       # Generate token
yantrikdb export <db> > backup.jsonl     # Export
yantrikdb import <db> < backup.jsonl     # Import
```

--------------------------------

### Start Voter Nodes

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Start the YantrikDB service on each voter node using its respective configuration file.

```bash
yantrikdb serve --config ./node1.toml
```

```bash
yantrikdb serve --config ./node2.toml
```

--------------------------------

### Start yql interactive client

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Connect to the YantrikDB server using the yql command-line interface.

```bash
yql --host 192.168.4.180 -p 7438 -t ydb_cluster_3a8f...
```

--------------------------------

### Install Python SDK dependencies

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Install the required httpx and msgpack packages to use the YantrikDB Python SDK.

```bash
pip install httpx msgpack
# Use sdk/python/yantrikdb (or vendor it into your project)
```

--------------------------------

### Initialize cluster node

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/README.md

Initialize a cluster node configuration and start the server using the generated TOML file.

```bash
yantrikdb cluster init \
  --node-id 1 \
  --output ./node1.toml \
  --peers 192.168.1.2:7440 \
  --witnesses 192.168.1.3:7440
yantrikdb serve --config ./node1.toml
```

--------------------------------

### Reproduce Benchmarks

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/papers/zenodo-bundle/README.md

Commands to clone the YantrikDB server repository, install necessary dependencies, and execute the benchmark scripts.

```bash
# Clone the YantrikDB server repository
git clone https://github.com/yantrikos/yantrikdb-server.git
cd yantrikdb-server/benchmarks/skill_recall

# Install dependencies
pip install tiktoken matplotlib

# Re-run all benchmarks
python token_cost_bench.py
python kill_test_ablation.py
python k_sensitivity_and_tokenizer_bench.py
python hallucination_admission_bench.py
```

--------------------------------

### Start SSE transport server

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/README.md

Command to start the MCP server using the SSE transport protocol on a specified port.

```bash
yantrikdb-mcp --transport sse --port 8420
```

--------------------------------

### Interact with YantrikDB using yql

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Example commands for connecting to the server and performing memory operations using the yql interactive client.

```bash
yql --host localhost -t "$(cat token.txt)"
yantrikdb> remember "Alice leads engineering at Acme" importance=0.9 domain=work
yantrikdb> recall who leads engineering
yantrikdb> \stats
yantrikdb> \q
```

--------------------------------

### GET /v1/admin/packs

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_031_server_packs.md

Lists all stored server packs.

```APIDOC
## GET /v1/admin/packs

### Description
Retrieves a list of all stored packs including their digest, name, size, and trust level.

### Method
GET

### Endpoint
/v1/admin/packs
```

--------------------------------

### Start the Witness Node

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Launch the witness process on the designated witness machine using the cluster secret.

```bash
yantrikdb-witness \
  --node-id 99 \
  --port 7440 \
  --cluster-secret <paste-secret> \
  --state-file ./witness-state.json
```

--------------------------------

### Conflict Detection Example

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/README.md

Example of how YantrikDB represents a contradiction between two memory records.

```text
"works at Google" (recorded Jan 15) vs. "works at Meta" (recorded Mar 1)
→ Conflict: identity_fact, priority: high, strategy: ask_user
```

--------------------------------

### Session Management and Temporal Queries

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/README.md

Demonstrates starting a session, recording memories, ending a session to compute metrics, and querying stale or upcoming memories.

```python
sid = db.session_start("default", "claude-code")
db.record("decided to use PostgreSQL")  # auto-linked to session
db.record("Alice suggested Redis for caching")
db.session_end(sid)
# → computes: memory_count, avg_valence, topics, duration

db.stale(days=14)    # high-importance memories not accessed recently
db.upcoming(days=7)  # memories with approaching deadlines
```

--------------------------------

### Execute chaos test scenarios

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/tests/chaos/README.md

Commands to start the cluster, run chaos scenarios, and tear down the environment.

```bash
# Start the 3-node cluster
docker compose -f tests/chaos/docker-compose.chaos.yml up -d

# Run all scenarios
python tests/chaos/run_chaos.py

# Run a specific scenario
python tests/chaos/run_chaos.py --scenario leader_kill

# Tear down
docker compose -f tests/chaos/docker-compose.chaos.yml down -v
```

--------------------------------

### yql interactive client commands and output

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Example commands for storing, recalling, and relating data within the yql shell, along with cluster management commands.

```text
yantrikdb> remember "Alice leads engineering" importance=0.9 domain=work
✓ stored: 019d623a-3d70-712e-9315-e1da5ee41114

yantrikdb> recall who leads engineering top=5
+---+-------+---------------------------------+--------+
| # | score | text                            | domain |
+---+-------+---------------------------------+--------+
| 1 | 1.41  | Alice leads engineering at Acme | work   |
+---+-------+---------------------------------+--------+

yantrikdb> relate Alice -> Acme as works_at
✓ edge: 019d623a-41cf-71a2 (Alice -[works_at]-> Acme)

yantrikdb> \cluster
yantrikdb> \stats
yantrikdb> \q
```

--------------------------------

### Install YantrikDB MCP package

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/README.md

Install the required Python package to enable YantrikDB memory tools in your MCP-compatible AI agent.

```bash
pip install yantrikdb-mcp
```

--------------------------------

### GET /v1/skills/{skill_id} response

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_022_skill_substrate_and_ryw.md

The 200 OK response containing skill details.

```json
{
  "rid":          "019de580-1234-...",
  "skill_id":     "skill.invoice.validation.v3",
  "body":         "When validating an invoice, ...",
  "applies_to":   ["invoice", "approval"],
  "skill_type":   "rule",
  "metadata":     { ... },
  "namespace":    "skill_substrate",
  "memory_type":  "procedural",
  "created_at":   1762012345.123
}
```

--------------------------------

### Run YantrikDB as a network server

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/README.md

Starts the YantrikDB container and performs a POST request to the remember endpoint.

```bash
docker run -p 7438:7438 ghcr.io/yantrikos/yantrikdb:latest
curl -X POST http://localhost:7438/v1/remember -d '{"text":"hello"}'
```

--------------------------------

### Trigger snapshot via POST /v1/admin/snapshot

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/migration/v0.7_to_v0.8.md

Example curl command to perform a database snapshot in single-node mode using a per-database token.

```bash
curl -X POST http://localhost:7438/v1/admin/snapshot \
  -H "Authorization: Bearer $YDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"database":"default","output_dir":"/var/lib/yantrikdb/snapshots"}'
```

--------------------------------

### GET /v1/pack-context

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_031_server_packs.md

Retrieves the pack context for the caller's tenant.

```APIDOC
## GET /v1/pack-context

### Description
Retrieves the mounted packs' pack_context (constitution and coverage) for the caller's tenant, intended for injection into system prompts.

### Method
GET

### Endpoint
/v1/pack-context
```

--------------------------------

### Rust SDK Usage

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/DESIGN.md

Example usage of the YantrikDB Rust SDK for asynchronous memory operations.

```rust
use yantrikdb::Client;

let db = Client::connect("yantrik://localhost:7437", "ydb_...")?;

db.remember("Alice leads engineering").importance(0.9).send().await?;
let results = db.recall("who leads engineering?").explain(true).send().await?;

let session = db.session("chat-42").start().await?;
session.remember("User asked about pricing").send().await?;
let results = session.recall("what's the user asking about?").send().await?;
session.end().await?;
```

--------------------------------

### HTTP /v1/lookup request and response

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_022_skill_substrate_and_ryw.md

Example of a POST request to the /v1/lookup endpoint and the corresponding 200 OK JSON response.

```http
POST /v1/lookup
Authorization: Bearer <token>
Content-Type: application/json

{
  "namespace": "skill_substrate",
  "field":     "skill_id",
  "value":     "skill.invoice.validation.v3"
}
```

```json
{
  "found":  true,
  "memory": {
    "rid":         "019de580-...",
    "text":        "...",
    "metadata":    { ... },
    "namespace":   "skill_substrate",
    "memory_type": "procedural",
    "created_at":  1762012345.123
  },
  "index_used": "skill_id"
}
```

--------------------------------

### POST /v1/recall Request and Response

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_022_skill_substrate_and_ryw.md

Example of a recall request with a where-clause prefilter and the corresponding explain response from the server.

```json
POST /v1/recall
Authorization: Bearer <token>
Content-Type: application/json

{
  "namespace": "skill_substrate",
  "query":     "How should I validate an invoice?",
  "top_k":     5,
  "where": {
    "all": [
      { "field": "record_type", "op": "eq",       "value": "skill" },
      { "field": "skill_type",  "op": "eq",       "value": "rule" },
      { "field": "applies_to",  "op": "contains", "value": "invoice" }
    ]
  },
  "explain": true
}
```

```json
{
  "results": [ ... ],
  "plan": {
    "filter_mode":              "indexed_prefilter",
    "indexes_used":             ["record_type", "skill_type", "applies_to"],
    "candidate_count":          384,
    "vector_strategy":          "exact_rerank_over_candidates",
    "estimated_distance_computations": 384,
    "fallback_used":            false
  }
}
```

--------------------------------

### Python SDK Usage

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/DESIGN.md

Example usage of the YantrikDB Python SDK for memory management and event subscription.

```python
from yantrikdb import connect

db = connect("yantrik://localhost:7437", token="ydb_...")

db.remember("Alice leads engineering", importance=0.9)
results = db.recall("who leads engineering?", explain=True)

with db.session("chat-42") as s:
    s.remember("User asked about pricing")
    results = s.recall("what's the user asking about?")

db.relate("Alice", "Engineering", "leads")
report = db.think()

for event in db.subscribe(["conflict", "decay"]):
    print(event)
```

--------------------------------

### GET /v1/admin/databases/{id}/packs

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_031_server_packs.md

Retrieves the status of mounted packs for a database.

```APIDOC
## GET /v1/admin/databases/{id}/packs

### Description
Returns the mounted packs, manifest, and reconcile state for the specified database.

### Method
GET

### Endpoint
/v1/admin/databases/{id}/packs

### Parameters
#### Path Parameters
- **id** (string) - Required - The database ID
```

--------------------------------

### Connection Lifecycle Sequence

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/DESIGN.md

A visual representation of the connection flow, from authentication and session start to memory operations, recall, event subscription, and session termination.

```text
Client                                    Server
  │                                         │
  ├── AUTH(token="ydb_abc123") ──────────►  │
  │                                         ├── validate token
  │  ◄──────────────── AUTH_OK(db="default")│
  │                                         │
  ├── SESSION_START(agent="bot-1") ──────►  │
  │  ◄──────── SESSION_OK(sid="sess_xyz")   │
  │                                         │
  ├── REMEMBER(text="User likes dark") ──►  │
  │  ◄──────── REMEMBER_OK(rid="mem_01")    │
  │                                         │
  ├── RECALL(query="user prefs") ────────►  │
  │  ◄──────── RECALL_RESULT(mem_01, 0.93)  │
  │  ◄──────── RECALL_RESULT(mem_07, 0.71)  │
  │  ◄──────── RECALL_END(total=2)          │
  │                                         │
  ├── SUBSCRIBE(events=["conflict"]) ────►  │
  │                                         │
  │  ... time passes ...                    │
  │                                         │
  │  ◄──────── EVENT(conflict_detected)     │  ← server push!
  │                                         │
  ├── SESSION_END(sid="sess_xyz") ───────►  │
  │  ◄──────── SESSION_OK(summary=...)      │
  │                                         │
```

--------------------------------

### GET /v1/skills/{skill_id} request

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_022_skill_substrate_and_ryw.md

Retrieves a specific skill by its ID.

```http
GET /v1/skills/{skill_id}
Authorization: Bearer <token>
```

--------------------------------

### Store and Search Memories via HTTP API

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Example using curl to store a memory with /v1/remember and perform a semantic search with /v1/recall, requiring a Bearer token.

```bash
TOKEN=ydb_cluster_3a8f...

curl -X POST http://192.168.4.180:7438/v1/remember \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Alice leads engineering at Acme", "importance": 0.9, "domain": "work"}'

curl -X POST http://192.168.4.180:7438/v1/recall \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "who leads engineering", "top_k": 5}'
```

--------------------------------

### Download pre-built binary

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/README.md

Download and prepare the latest pre-built binary for Linux.

```bash
wget https://github.com/yantrikos/yantrikdb-server/releases/latest/download/yantrikdb-linux-amd64
chmod +x yantrikdb-linux-amd64
```

--------------------------------

### Reproduce skill recall benchmark

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/benchmarks/skill_recall/RESULTS.md

Shell commands to set up the environment, generate data, seed the database, and run the benchmark scripts.

```bash
cd benchmarks/skill_recall
docker compose up -d

# Mint a token (the running server auto-creates a 'default' database).
docker exec yantrikdb-skill-bench yantrikdb token \
  --data-dir /var/lib/yantrikdb create --db default --label bench
# (capture printed token)
export YDB_TOKEN=ydb_...

python generate.py 5000
python seed.py    --nodes 127.0.0.1 --port 17438 --rate-per-sec 50
python bench.py   --nodes 127.0.0.1 --port 17438
python cache_bench.py --nodes 127.0.0.1 --port 17438

docker compose down -v   # cleanup
```

--------------------------------

### Create Database on Voter Nodes

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Initialize the database on each voter node. The witness node does not require this step.

```bash
yantrikdb db --data-dir ./data create default
```

--------------------------------

### Extended /v1/health response structure

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_010_pr6_write_path_migration.md

Example JSON response for the health endpoint, including new fields for replication lag, commit log status, and last applied timestamps.

```json
{
  "status": "healthy",
  "raft_mode": "openraft",
  "cluster": {
    "node_id": 2,
    "leader_id": 4,
    "term": 5,
    "last_log_index": 1842,
    "last_applied": 1842,
    "members": [...],
    "replication_lag_log_entries": 0,        // NEW
    "last_applied_at_unix_micros": 1779983412345678,  // NEW
    "commit_log_max_high_watermark": 39427    // NEW
  },
  "single_node": null
}
```

--------------------------------

### GET /v1/contest Response JSON

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_008_http_surface.md

The response body for the GET /v1/contest endpoint, containing the proposition ID, contest state metrics, and exemplar conflict pairs.

```json
{
  "proposition_id": "<uuid>",
  "regime": "default",
  "contest_state": {
    "proposition_id": "<uuid>",
    "regime": "default",
    "support_mass": 1.600,
    "attack_mass": 3.578,
    "support_effective_independence": 1.600,
    "attack_effective_independence": 3.578,
    "support_distinct_source_count": 2,
    "attack_distinct_source_count": 4,
    "same_source_opposite_polarity_count": 0,
    "same_artifact_extractor_polarity_conflict_count": 0,
    "temporal_overlap_conflict_count": 4,
    "temporal_separable_opposition_count": 4,
    "referent_schema_heterogeneity_count": 0,
    "heuristic_flags": 16,
    "derivation_version": 1,
    "content_hash": "<blake3>",
    "live_claim_count": 6,
    "state_status": "fresh",
    "computed_at": 1745011234
  },
  "exemplar_pairs": {
    "proposition_id": "<uuid>",
    "regime": "default",
    "heuristic_flags": 16,
    "same_source_opposite_polarity_pairs": [],
    "same_artifact_extractor_conflict_pairs": [],
    "temporal_overlap_conflict_pairs": [
      ["claim_id_A", "claim_id_B"],
      ["claim_id_A", "claim_id_C"],
      ["claim_id_D", "claim_id_B"],
      ["claim_id_D", "claim_id_C"]
    ]
  }
}
```

--------------------------------

### Run YantrikDB Skill Recall Benchmarks

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/benchmarks/skill_recall/README.md

Commands to boot the database, mint an access token, generate data, and execute the benchmark scripts. Windows users must prefix docker exec commands with MSYS_NO_PATHCONV=1 to avoid path conversion issues.

```bash
# 1. Boot a single-node YantrikDB locally.
cd benchmarks/skill_recall
docker compose up -d

# 2. Mint a token. The server creates a "default" db on startup; we mint a
#    token against it via a sidecar exec so the running server reads the
#    same control.db.
#
# WINDOWS / Git Bash users: prefix `docker exec` calls with
# `MSYS_NO_PATHCONV=1` — without it, MSYS rewrites the absolute Linux
# paths (`/var/lib/yantrikdb`) to a Windows-style path
# (`C:/Program Files/Git/var/lib/yantrikdb`) before they reach docker.
# The CLI then writes to the wrong location inside the container, so
# the token row never lands in the `control.db` the server reads.
# Symptom: token create succeeds but `/v1/remember` returns "invalid or
# revoked token" against the freshly-minted token.
#
docker exec yantrikdb-skill-bench yantrikdb db --data-dir /var/lib/yantrikdb \
  list   # confirm 'default' exists
docker exec yantrikdb-skill-bench yantrikdb token --data-dir /var/lib/yantrikdb \
  create --db default --label bench
# → save the printed token

export YDB_TOKEN=<token>

# 3. Generate corpus + queries (deterministic, seed=42).
python generate.py 5000

# 4. Seed.
python seed.py --nodes 127.0.0.1 --port 17438 --rate-per-sec 50

# 5. Recall benchmark.
python bench.py --nodes 127.0.0.1 --port 17438

# 6. Exact-id cache benchmark.
python cache_bench.py --nodes 127.0.0.1 --port 17438
```

--------------------------------

### GET /v1/admin/audit

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_030_admin_rbac.md

Reads the audit trail for administrative actions.

```APIDOC
## GET /v1/admin/audit

### Description
Reads the audit trail for administrative actions. Requires admin role.

### Method
GET

### Endpoint
/v1/admin/audit

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of records to return
- **kind** (string) - Optional - Filter by audit event kind
```

--------------------------------

### GET /v1/admin/me

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_030_admin_rbac.md

Retrieves the current actor's information and role.

```APIDOC
## GET /v1/admin/me

### Description
Retrieves the current actor's information and role, which is used to drive the role-aware UI.

### Method
GET

### Endpoint
/v1/admin/me
```

--------------------------------

### GET /v1/health

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Retrieves the health status and cluster information of the node.

```APIDOC
## GET /v1/health

### Description
Returns the current health status and cluster status of the YantrikDB node.

### Method
GET

### Endpoint
/v1/health
```

--------------------------------

### Run the LongMemEval benchmark harness

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/benchmarks/longmemeval/README.md

Commands to boot the YantrikDB environment, generate an access token, fetch the dataset, execute the benchmark, and aggregate the results.

```bash
# 1. Boot YantrikDB (same single-node config as skill_recall).
cd benchmarks/longmemeval
docker compose up -d

# 2. Mint a token (Windows / Git Bash users: prefix with MSYS_NO_PATHCONV=1).
docker exec yantrikdb-lme yantrikdb db --data-dir /var/lib/yantrikdb create default
docker exec yantrikdb-lme yantrikdb token --data-dir /var/lib/yantrikdb create --db default --label bench

export YDB_TOKEN=<token>

# 3. Pull the oracle variant (15 MB, fastest harness validation).
python fetch.py --variant oracle

# 4. Run the harness end-to-end.
python run.py --variant oracle --port 7438 --top-k 10 --limit 50

# 5. Aggregate metrics.
python metrics.py results_oracle.jsonl
```

--------------------------------

### GET /v1/mobility

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_008_http_surface.md

Retrieves the 13-dimensional mobility state for a specific proposition triple.

```APIDOC
## GET /v1/mobility

### Description
Read the 13-dim mobility state for a proposition. Returns the Warrant Flow vector including support, attack, temporal coherence, and other components.

### Method
GET

### Endpoint
/v1/mobility

### Parameters
#### Query Parameters
- **src** (string) - Required - The source of the triple.
- **rel_type** (string) - Required - The relation type of the triple.
- **dst** (string) - Required - The destination of the triple.
- **namespace** (string) - Optional - The namespace (default: default).
- **regime** (string) - Optional - The regime (default: default).

### Response
#### Success Response (200)
- **proposition_id** (string) - The UUID of the proposition.
- **regime** (string) - The regime context.
- **mobility_state** (object) - The 13-dimensional mobility state vector.

#### Response Example
{
  "proposition_id": "<uuid>",
  "regime": "default",
  "mobility_state": {
    "proposition_id": "<uuid>",
    "regime": "default",
    "snapshot_ts": 1745011234.123,
    "support_mass": 1.600,
    "attack_mass": 3.578,
    "modality_consilience": 0.167,
    "self_gen_local": 0.0,
    "temporal_coherence": 0.8,
    "load_bearingness": 4.0,
    "self_gen_ancestral": 0.0,
    "tier_write_components": ["support_mass", "attack_mass", "modality_consilience", "self_gen_local"],
    "tier_bg_components": ["temporal_coherence", "load_bearingness", "self_gen_ancestral"],
    "formula_version": 1,
    "content_hash": "<blake3>",
    "live_claim_count": 6,
    "state_status": "fresh",
    "computed_at": 1745011234
  }
}
```

--------------------------------

### GET /v1/skills/{skill_id}

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/papers/skill-substrate-experience-report-v4.md

Performs an exact lookup of a skill by its unique identifier.

```APIDOC
## GET /v1/skills/{skill_id}

### Description
Performs an exact lookup of a skill by its unique identifier.

### Method
GET

### Endpoint
/v1/skills/{skill_id}

### Parameters
#### Path Parameters
- **skill_id** (string) - Required - The unique identifier of the skill.
```

--------------------------------

### Run LongMemEval benchmark reproduction commands

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/benchmarks/longmemeval/RESULTS.md

Commands to initialize the YantrikDB container, create a database, generate an access token, fetch benchmark data, run the evaluation harness, and aggregate results.

```bash
cd benchmarks/longmemeval
docker compose up -d
MSYS_NO_PATHCONV=1 docker exec yantrikdb-lme yantrikdb db --data-dir /var/lib/yantrikdb create default
TOKEN=$(MSYS_NO_PATHCONV=1 docker exec yantrikdb-lme yantrikdb token \
  --data-dir /var/lib/yantrikdb create --db default --label lme | grep '^ydb_')
python fetch.py --variant oracle
YDB_TOKEN=$TOKEN python run.py --variant oracle --port 18438
python metrics.py results_oracle.jsonl
```

--------------------------------

### Benchmark Token Savings

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/README.md

Run the benchmark script to reproduce token savings metrics.

```bash
python benchmarks/bench_token_savings.py
```

--------------------------------

### Backup cluster snapshot

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/migration/v0.7_to_v0.8.md

Execute this command from the current leader to create a database snapshot before performing the migration.

```bash
curl -X POST http://leader:7438/v1/admin/snapshot \
  -H "Authorization: Bearer $CLUSTER_MASTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"database":"default"}'
```

--------------------------------

### GET /v1/flagged_propositions Response

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_008_http_surface.md

The response structure for listing propositions that intersect with the provided bitmask.

```json
{
  "flagged_propositions": [
    { "proposition_id": "...", "regime": "default", "heuristic_flags": 16, ... },
    ...
  ],
  "flag_mask": 16,
  "count": 1
}
```

--------------------------------

### GET /v1/mobility not found response

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_008_http_surface.md

The response returned when no claims have been ingested for the specified triple.

```json
{
  "mobility_state": null,
  "proposition_id": null,
  "reason": "proposition not found — no claims ingested for this triple yet"
}
```

--------------------------------

### Run Rashomon Engine via CLI

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/showcase/rashomon_engine.md

Execute the engine using the provided Python script with your authentication token and cluster URL.

```bash
python docs/showcase/rashomon_engine.py ydb_your_token http://your-cluster:7438
```

--------------------------------

### Token Management Initialization

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/admin/studio.html

Initializes the UI for viewing and minting tokens.

```javascript
async function renderTokens(){ $('appview').innerHTML=`<div class="panel"><h2>Tokens</h2><div id="reveal"></div><div id="toklist" class="empty">Loading…</div> ${can('admin')?`<div class="form"><select id="tokdb"></select><input id="toklabel" placeholder="label (optional)" style="flex:.7"/><button class="btn" onclick="mintTok()">Mint</button></div> <div class="note">The plaintext token is shown once.
```

--------------------------------

### GET /v1/contest

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_008_http_surface.md

Retrieves the contest state for a given source, relation, destination, namespace, and regime.

```APIDOC
## GET /v1/contest

### Description
Read contest state (Γ(c) — the structured contradiction signature). Returns 5 grounded counters, 5 heuristic flags, and on-demand exemplar claim_id pairs.

### Method
GET

### Endpoint
/v1/contest

### Parameters
#### Query Parameters
- **src** (string) - Required - Source identifier
- **rel_type** (string) - Required - Relation type
- **dst** (string) - Required - Destination identifier
- **namespace** (string) - Required - Namespace identifier
- **regime** (string) - Required - Regime identifier

### Response
#### Success Response (200)
- **proposition_id** (string) - Unique identifier for the proposition
- **regime** (string) - The regime used
- **contest_state** (object) - Structured state containing counters and flags
- **exemplar_pairs** (object) - On-demand claim_id pairs

#### Response Example
{
  "proposition_id": "<uuid>",
  "regime": "default",
  "contest_state": {
    "proposition_id": "<uuid>",
    "regime": "default",
    "support_mass": 1.600,
    "attack_mass": 3.578,
    "support_effective_independence": 1.600,
    "attack_effective_independence": 3.578,
    "support_distinct_source_count": 2,
    "attack_distinct_source_count": 4,
    "same_source_opposite_polarity_count": 0,
    "same_artifact_extractor_polarity_conflict_count": 0,
    "temporal_overlap_conflict_count": 4,
    "temporal_separable_opposition_count": 4,
    "referent_schema_heterogeneity_count": 0,
    "heuristic_flags": 16,
    "derivation_version": 1,
    "content_hash": "<blake3>",
    "live_claim_count": 6,
    "state_status": "fresh",
    "computed_at": 1745011234
  },
  "exemplar_pairs": {
    "proposition_id": "<uuid>",
    "regime": "default",
    "heuristic_flags": 16,
    "same_source_opposite_polarity_pairs": [],
    "same_artifact_extractor_conflict_pairs": [],
    "temporal_overlap_conflict_pairs": [
      ["claim_id_A", "claim_id_B"],
      ["claim_id_A", "claim_id_C"],
      ["claim_id_D", "claim_id_B"],
      ["claim_id_D", "claim_id_C"]
    ]
  }
}
```

--------------------------------

### Run backfill-from-engine admin tool

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_010_pr6_write_path_migration.md

Executes the backfill tool to synthesize commit log entries for existing memories. The tool is idempotent and requires cluster mTLS with admin:backfill capability.

```bash
yantrikdb admin backfill-from-engine \
    --tenant-id 1 \
    --confirm

Will synthesize ~39427 commit log entries for tenant 1.
Estimated time: 8 minutes at 80 entries/sec.
Existing log entries (will not be overwritten): 0
Continue? [yes]
```

--------------------------------

### Load Database Packs

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/admin/studio.html

Fetches and renders the list of packs mounted to a specific database, including options to mount new packs if authorized.

```javascript
window.loadDbPacks=async function(){ const id=Number($('pack-db').value); if(!id){$('dbpacks').innerHTML='<div class="empty">Select a database.</div>';return;} try{ const {manifest,status}=await api('/v1/admin/databases/'+id+'/packs'); const state=d=>status.mounted.includes(d)?'<span class="badge follower">mounted</span>' :status.poisoned.includes(d)?'<span class="badge quarantined">poisoned</span>':'<span class="badge witness">pending</span>'; const mountedDigests=new Set(manifest.map(m=>m.pack_digest)); const avail=(window._packs||[]).filter(p=>!mountedDigests.has(p.digest)); $('dbpacks').innerHTML=`${manifest.length?`<table><thead><tr><th>Pack</th><th>Digest</th><th>State</th>${can('admin')?'<th></th>':''}</tr></thead><tbody>${ manifest.map(m=>`<tr><td><b>${esc(m.pack_name)}</b></td><td class="mono">${esc(m.pack_digest.slice(0,12))}…</td><td>${state(m.pack_digest)}</td> ${can('admin')?`<td class="rowacts"><button class="btn danger sm" onclick="unmountPack(${id},'${esc(m.pack_digest)}')">Unmount</button></td>`:''}</tr>`).join('')}</tbody></table>` :'<div class="empty">No packs mounted in this database.</div>'} ${can('admin')&&avail.length?`<div class="form" style="margin-top:.8rem"><select id="mount-pick">${avail.map(p=>`<option value="${p.digest}">${esc(p.digest.slice(0,16))}…</option>`).join('')}</select> <input id="mount-name" placeholder="label (optional)" style="flex:.7"/><button class="btn" onclick="mountPack(${id})">Mount</button></div>`:''}`; }catch(e){ $('dbpacks').innerHTML=`<div class="empty">${esc(e.message)}</div>`; } };
```

--------------------------------

### Build Docker images for chaos testing

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/tests/chaos/README.md

Build the required Docker images for the YantrikDB server and witness nodes before running tests.

```bash
docker build -f docker/Dockerfile.yantrikdb -t yantrikdb:chaos .
docker build -f docker/Dockerfile.witness -t yantrikdb-witness:chaos .
```

--------------------------------

### Regenerate data-dir-v1 fixtures

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/tests/fixtures/README.md

Commands to create a new test database and generate a token within the data-dir-v1 directory.

```bash
cargo run -p yantrikdb-server -- db --data-dir tests/fixtures/data-dir-v1 create test
cargo run -p yantrikdb-server -- token --data-dir tests/fixtures/data-dir-v1 create --db test --label compat-test
```

--------------------------------

### Add and promote new cluster nodes

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/migration/v0.7_to_v0.8.md

Commands to add a new node as a learner, wait for it to catch up, and promote it to a voter.

```bash
# On the new node, populate /var/lib/yantrikdb from leader's tar
# (excluding raft_log.sqlite*, raft.json, commit_log.sqlite*).
# Start the new node — it'll come up as a learner discovering
# the leader via cluster_secret.

# On any host with master token + network access to the leader:
yantrikdb cluster add-learner \
  --node-id 4 --addr http://192.168.4.140:7438 \
  --leader http://192.168.4.141:7438 \
  --master-token "$YDB_CLUSTER_MASTER_TOKEN"

yantrikdb cluster wait-caught-up \
  --node-id 4 --leader http://192.168.4.141:7438 \
  --master-token "$YDB_CLUSTER_MASTER_TOKEN"

yantrikdb cluster promote-voter \
  --voters 2,4 \
  --leader http://192.168.4.141:7438 \
  --master-token "$YDB_CLUSTER_MASTER_TOKEN"
```

--------------------------------

### POST /v1/databases

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Creates a new database.

```APIDOC
## POST /v1/databases

### Description
Creates a new database instance.

### Method
POST

### Endpoint
/v1/databases
```

--------------------------------

### GET /v1/admin/maintenance/status

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_027_active_memory_server.md

Retrieves the status of the last maintenance cycle for a database tenant, including worker liveness and execution details.

```APIDOC
## GET /v1/admin/maintenance/status

### Description
Retrieves the persisted status of the last maintenance cycle for a tenant, including the timestamp, sub-report counts, and any errors.

### Method
GET

### Endpoint
/v1/admin/maintenance/status

### Query Parameters
- **tenant** (string) - Optional - The identifier of the database tenant to query.

### Response
#### Success Response (200)
- **status** (object) - Contains 'ran_at', sub-report counts, and error details.
```

--------------------------------

### Render Admin Users View

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-server/src/admin/studio.html

Initializes the user management panel, verifying owner role permissions before displaying the creation form.

```javascript
async function renderUsers(){ if(!can('owner')){ $('appview').innerHTML='<div class="empty">Owner role required.</div>'; return; } $('appview').innerHTML=`<div class="panel"><h2>Admin users</h2><div id="userlist" class="empty">Loading…</div> <div class="form"><input id="uname" placeholder="username"/><input id="upass" type="password" placeholder="password (≥8)"/> <select id="urole"><option value="readonly">readonly</option><option value="admin">admin</option><option value="owner">owner</option></select> <button class="btn" onclick="createUser()">Create</button></div> <div class="note">Passwords are argon2id-hashed; only the hash replicates.
```

--------------------------------

### Initialize Cluster Configuration on Node 2

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Generate the configuration file for the second voter node using the secret generated on node 1.

```bash
yantrikdb cluster init \
  --node-id 2 \
  --output ./node2.toml \
  --data-dir ./data \
  --peers 192.168.4.180:7440,192.168.4.183:7440 \
  --witnesses 192.168.4.183:7440 \
  --secret <paste-secret-from-node1>
```

--------------------------------

### System and Monitoring

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/DESIGN.md

Endpoints for system health, events, and configuration.

```APIDOC
## GET /v1/health
### Description
Returns server health status, including PING/PONG and statistics.

## GET /v1/events
### Description
Provides an SSE stream for event notifications.

## GET /v1/triggers
### Description
Reads the current trigger state.

## GET /v1/personality
### Description
Retrieves the current personality configuration.
```

--------------------------------

### GET /v1/flagged_propositions

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/docs/rfcs/rfc_008_http_surface.md

Lists propositions whose heuristic flags intersect with the provided bitmask, serving as a primary audit entry point.

```APIDOC
## GET /v1/flagged_propositions

### Description
List propositions whose contest_state.heuristic_flags intersects the given bitmask. Primary audit entry point.

### Method
GET

### Endpoint
/v1/flagged_propositions

### Parameters
#### Query Parameters
- **flag_mask** (u64) - Required - Bitmask to filter propositions.
- **limit** (integer) - Optional - Number of results to return (default 50).

### Response
#### Success Response (200)
- **flagged_propositions** (array) - List of propositions matching the mask.
- **flag_mask** (u64) - The mask used for the query.
- **count** (integer) - Total count of returned propositions.

#### Response Example
{
  "flagged_propositions": [
    { "proposition_id": "...", "regime": "default", "heuristic_flags": 16 }
  ],
  "flag_mask": 16,
  "count": 1
}
```

--------------------------------

### YantrikDB MCP Server Instructions

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/MCP_REDESIGN.md

Reference configuration for .claude/mcp.json to enable automatic memory recall, storage, and relationship mapping for AI agents.

```text
YantrikDB is your persistent cognitive memory. Use it AUTOMATICALLY.

## Auto-recall (before responding)
- At conversation start, call `recall` with a summary of the user's first message
- When the user references past work, decisions, people, or preferences, call `recall`

## Auto-remember (during conversation)
Proactively call `remember` whenever you encounter:
- Decisions made, user preferences, people & relationships, project context, corrections, important facts

## Auto-relate (knowledge graph)
Call `relate` when you learn about entity relationships

## What NOT to remember
- Ephemeral task details, things derivable from code/git, verbatim code

## Memory quality
- Use specific, searchable text
- Set importance: 0.8-1.0 critical, 0.5-0.7 useful, 0.3-0.5 minor
- Set domain: "work", "preference", "architecture", "people", "infrastructure"
```

--------------------------------

### Initialize Cluster Configuration on Node 1

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/SERVER_README.md

Generate the initial cluster configuration file on the first voter node. Copy the resulting cluster_secret for use on other nodes.

```bash
yantrikdb cluster init \
  --node-id 1 \
  --output ./node1.toml \
  --data-dir ./data \
  --peers 192.168.4.181:7440,192.168.4.182:7440 \
  --witnesses 192.168.4.183:7440
```

--------------------------------

### Deploy HA Cluster

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/deploy/kubernetes/README.md

Steps to configure a cluster secret, deploy the StatefulSet, initialize the database, and verify connectivity with authentication.

```bash
# 1. Update the cluster secret
kubectl create secret generic yantrikdb-cluster-secret \
  --from-literal=cluster-secret="$(openssl rand -hex 32)"

# 2. Deploy
kubectl apply -f yantrikdb-cluster.yaml

# 3. Wait for pods
kubectl rollout status statefulset/yantrikdb

# 4. Create database + token
kubectl exec yantrikdb-0 -- yantrikdb db --data-dir /data create mydb
TOKEN=$(kubectl exec yantrikdb-0 -- yantrikdb token --data-dir /data create --db mydb --label k8s)
echo "Token: $TOKEN"

# 5. Port-forward and test
kubectl port-forward svc/yantrikdb 7438:7438
curl -H "Authorization: Bearer $TOKEN" http://localhost:7438/v1/stats
```

--------------------------------

### Run yantrikdb-witness

Source: https://github.com/yantrikos/yantrikdb-server/blob/main/crates/yantrikdb-witness/README.md

Execute the witness daemon with the required node ID, port, cluster secret, and state file path.

```bash
yantrikdb-witness \
  --node-id 99 \
  --port 7440 \
  --cluster-secret <shared-secret> \
  --state-file ./witness-state.json
```