YantrikDB

https://github.com/yantrikos/yantrikdb
Admin
YantrikDB is a cognitive memory engine for persistent AI systems that provides semantic recall,...
Tokens:49,656
Snippets:650
Trust Score:6.8
License:Apache-2.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### Verify, install, and serve a capability

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/QUICKSTART.md

Verifies the capability bundle, installs it into the database, and starts the server for the specified base model.

```bash
python packs/bundle.py verify  dist/motion-craft-0.1.0.ycap
python packs/bundle.py install dist/motion-craft-0.1.0.ycap --db mem.db
python packs/bundle.py list    --db mem.db

.venv-compile/bin/python packs/serve_compiled.py \
    --base Qwen/Qwen3.5-4B --db mem.db --port 11555 &
```

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

### Install and Compile Site

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/letterpress/README.md

Install the package and compile a site definition file into an HTML page.

```bash
pip install yantrik-letterpress
letterpress compile site.ops --out site.html --strict
```

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

### Sync usage example

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/sync-transport.md

Complete example demonstrating how to initialize a server and perform a single sync operation with a client.

```python
import asyncio
from yantrikdb import YantrikDB
from yantrikdb.sync.transport import SyncServer, SyncClient

async def main():
    db = YantrikDB.with_default("node.db")
    server = SyncServer(db, host="0.0.0.0", port=8765)
    await server.start()

    client = SyncClient(db, "ws://peer:8765")
    try:
        report = await client.sync_once()
        print("pushed", report["pushed"], "pulled", report["pulled"])
    finally:
        await server.stop()

asyncio.run(main())
```

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

### Install dependencies for capability execution

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/QUICKSTART.md

Sets up a virtual environment and installs the required PyTorch and transformer libraries. Requires a 24 GB GPU.

```bash
python -m venv .venv-compile
.venv-compile/bin/pip install torch --index-url https://download.pytorch.org/whl/cu124
.venv-compile/bin/pip install transformers peft accelerate datasets bitsandbytes
```

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

### Example Page Section Configurations

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/letterpress/corpus.md

Examples of section sequences for different business types, demonstrating how to arrange components between the hero and cta sections.

```text
a bakery            hero  features  roster  detail  faq   cta
a physio clinic     hero  features  detail  roster  faq   cta
an open-source CLI  hero  features  detail  faq     cta
a film archive      hero  proof     detail  features note cta
```

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

### Install and run Letterpress

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/letterpress/constitution.md

Commands to install the package and execute the compiler on an operations file.

```bash
pip install yantrik-letterpress==0.1.0
letterpress photos site.ops        # only if the ops use photo=
letterpress compile site.ops --out site.html --strict
```

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

### Bundle and verify capabilities

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/CAPABILITIES.md

Build, verify, install, and list capabilities using the bundle utility.

```bash
python packs/bundle.py build <pack>-craft --tag v1 --version 0.1.0 --key <sk>
python packs/bundle.py verify packs/dist/<pack>-0.1.0.ycap
python packs/bundle.py install packs/dist/<pack>-0.1.0.ycap --db mem.db
python packs/bundle.py list --db mem.db
```

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

### Letterpress operation syntax example

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/letterpress/corpus.md

A complete example demonstrating the seven letterpress operations, including site configuration, theme selection, section definition, and content population.

```text
SITE     name="Tide Mill"  nav="Bread,Visit,Contact"  location="Bristol"  contact="hello@tidemill.co"
THEME    family=editorial  accent=#b8442f  mode=light  density=roomy
SECTION  id=s1  kind=hero  layout=split  tone=quiet
TEXT     sec=s1  slot=eyebrow  text="Weekly loaf"
TEXT     sec=s1  slot=title    text="Bread [worth the walk]"
TEXT     sec=s1  slot=lede     text="Two ovens and no cafe. We bake twice a week and sell out by noon."
ACTION   sec=s1  slot=primary    label="Collection times"  href="#times"
ACTION   sec=s1  slot=secondary  label="This week's loaf"  href="#loaf"
MEDIA    sec=s1  slot=figure  motif=lattice
ITEM     sec=s2  slot=item  title="Tuesday"  body="Rye and caraway, forty loaves. Mixed by hand and proofed overnight in the cool cellar."
```

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

### Setup and run Agent Memory Benchmark

Source: https://github.com/yantrikos/yantrikdb/blob/main/docs/benchmarks/beam-frozen-context.md

Initializes the environment and executes the end-to-end benchmark run for YantrikDB.

```bash
git clone https://github.com/vectorize-io/agent-memory-benchmark
cd agent-memory-benchmark
uv sync

python /path/to/yantrikdb/benchmarks/amb/install.py .

YDB_BENCH_TURN_AWARE=1 YDB_BENCH_TOPK=40 \
  uv run amb run --dataset beam --split 100k --memory yantrikdb -n ydb-final
```

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

### TenantManager Usage Example

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/tenant-manager.md

Demonstrates how to initialize the manager, register tenants with and without encryption, retrieve a database instance, and list all tenants.

```python
import os
from yantrikdb import TenantManager

mgr = TenantManager("/data/tenants", embedding_dim=256)
mgr.register_tenant("acme", encryption_key=os.urandom(32))
mgr.register_tenant("globex")

db = mgr.get("acme")
db.record("Alice is the engineering lead", domain="people")
print(db.is_encrypted(), db.actor_id)
db.close()

print(mgr.discovered_tenants())  # ['acme', 'globex']
```

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

### List installed packs

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/yantrikdb-pack-api/corpus.md

Retrieve a list of packs recorded as durably installed.

```python
db.installed_packs()
```

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

### SyncServer usage

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/sync-transport.md

Basic lifecycle management for starting and stopping a SyncServer instance.

```python
server = SyncServer(db, host="0.0.0.0", port=8765)
await server.start()
# ...
await server.stop()
```

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

### Registering an action hook

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/wordpress-expert/corpus.md

Example of registering a function to the 'init' hook using add_action.

```php
add_action('init', 'myplugin_register')
```

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

### Install YantrikDB

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

Install the library using pip. No additional dependencies like sentence-transformers or ONNX runtime are required.

```bash
pip install yantrikdb
```

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

### Basic YantrikDB usage example

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/yantrikdb-class.md

Demonstrates initializing a database, recording information, and checking embedder status.

```python
import yantrikdb

db = yantrikdb.YantrikDB.with_default("memory.db")
print(db.actor_id, db.embedder_identity())
db.record("Alice is the engineering lead", importance=0.8, domain="people")
print(db.has_embedder(), db.detect_embedder_window())
db.close()
```

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

### Verify Site Rendering

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/letterpress/README.md

Install verification dependencies and run the shoot command to validate rendering, contrast, and accessibility constraints.

```bash
pip install 'yantrik-letterpress[verify]'
python -m playwright install chromium
letterpress shoot site.html
```

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

### Install custom embedder support

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/yantrikdb-engine/corpus.md

Install the sentence-transformers dependency to use your own embedder.

```bash
pip install yantrikdb[sentence-transformers]
```

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

### Run build and test commands

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/gamekit/charforge/README.md

Commands to install dependencies, build the character viewer, and run headless verification gates.

```bash
npm install
node build.mjs     # -> dist/forge.html (open in any browser)
node gates.mjs     # headless gates + screenshots
```

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

### Initialize YantrikDB with Default Embedder

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/yantrikdb-class.md

Example usage of the with_default constructor to open a file-backed store.

```python
db = yantrikdb.YantrikDB.with_default("memory.db")
```

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

### Organizing and recalling evidence

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/organize.md

A complete example showing how to initialize the database, record evidence, organize it using a discover function, and perform a recall.

```python
import yantrikdb
from yantrikdb import organize_evidence, recall_organized

db = yantrikdb.YantrikDB.with_default("memory.db")
db.record_batch([
    {"text": "deadline moved to March 30", "metadata": {"evidence": "e1"}},
    {"text": "Alice prefers dark mode", "metadata": {"evidence": "e2"}},
    {"text": "deadline discussion at launch sync", "metadata": {"evidence": "e3"}},
])

def discover(evidence: dict[str, str]):
    return [
        {"id": "t-deadlines", "label": "Deadlines",
         "summary": "Project deadline facts", "evidence_ids": ("e1", "e3")},
        {"id": "t-prefs", "label": "Preferences",
         "summary": "User preferences", "evidence_ids": ("e2",)},
    ]

plan, writes = organize_evidence(db, {"e1": "...", "e2": "...", "e3": "..."},
                                 discover)
assert not plan.unassigned_evidence_ids

hits = recall_organized(db, "summarize the deadlines", mode="handles")
for h in hits:
    print(h["rid"], h["metadata"].get("organizer_label"))
```

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

### Seal, mount, and recall from packs

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/packs.md

Example demonstrating how to seal a pack, mount it to a database, and perform a recall operation with specific constraints.

```python
import yantrikdb

db = yantrikdb.YantrikDB.with_default("memory.db")
manifest = db.seal_pack(
    "compendium.ydbpack", name="Compendium", version="1.0.0",
    origin="acme", namespace="knowledge",
    constitution=["Never claim a fact you cannot cite."],
    recommended_top_k=20,
)
print(manifest["pack_id"], manifest["content_digest"])

db2 = yantrikdb.YantrikDB.with_default("app.db")
try:
    db2.mount_pack("compendium.ydbpack")
except yantrikdb.PackEmbedderMismatch as e:
    # spaces merely unproven? accept explicitly; proven mismatch -> rebuild
    db2.mount_pack("compendium.ydbpack", allow_unverified_embedder=True)
print(db2.pack_context())
hits = db2.recall_from_packs_for(["acme@1.0.0"], query="deadlines",
                                 min_similarity=0.3)
```

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

### Using OpenAI Agents Adapter

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/adapters.md

Example of retrieving available tools and executing a memory_record tool call using the adapter.

```python
from yantrikdb.adapters.openai_agents import get_tools, handle_tool_call

tools = get_tools()
result = handle_tool_call(db, "memory_record",
                          {"text": "deploy with blue-green",
                           "importance": 0.8})
print(result)  # {"rid": "..."}
```

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

### Usage example

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/rerank.md

Demonstrates basic usage of recall_reranked and rerank_hits.

```python
import yantrikdb
from yantrikdb import recall_reranked, rerank_hits

db = yantrikdb.YantrikDB.with_default("memory.db")
db.record("deploy with blue-green, not rolling update", domain="devops")

# basic
best = recall_reranked(db, "how should we ship?", top_k=3, pool_k=20,
                       namespace="devops")
for hit in best:
    print(round(hit["rerank_score"], 4), hit["text"])

# rerank an existing result list
hits = db.recall("how should we ship?", top_k=50)
reranked = rerank_hits("how should we ship?", hits, top_k=5, clip=800)
```

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

### Clone and Install YantrikDB

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/QUICKSTART.md

Commands to clone the repository and set up a virtual environment for CPU-only verification.

```bash
git clone https://github.com/yantrikos/yantrikdb
cd yantrikdb
python -m venv .venv && .venv/bin/pip install yantrikdb
```

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

### Site Definition Language Example

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/letterpress/README.md

An example of the seven-operation language used to define site structure, themes, and content.

```text
SITE     name="Tide Mill"  nav="Bread,Visit"  location="Bristol"  contact="hello@tidemill.co"
THEME    family=editorial  accent=#b8442f  mode=light  density=roomy
SECTION  id=s1  kind=hero  layout=split  tone=quiet
TEXT     sec=s1  slot=title  text="Bread [worth the walk]"
TEXT     sec=s1  slot=lede   text="Two ovens and no cafe. We sell out by noon."
ACTION   sec=s1  slot=primary  label="Collection times"  href="#times"
MEDIA    sec=s1  slot=figure  photo="sourdough bread bakery"
ITEM     sec=s2  slot=item  title="Tuesday"  body="Rye and caraway, forty loaves."
```

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

### Basic YantrikDB usage example

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/graph-cognition.md

Demonstrates initializing the database, recording data, attaching claims, relating entities, and running cognition tasks.

```python
import yantrikdb

db = yantrikdb.YantrikDB.with_default("memory.db")
db.record("Alice leads Engineering", source="user")
db.attach_claims(rid, [{"src": "Alice", "rel_type": "leads", "dst": "Engineering"}])
print(db.get_claims("Alice"))
db.relate("Alice", "Engineering", "leads")

report = db.think({"run_pattern_mining": True, "run_conflict_scan": True})
for t in db.get_pending_triggers(limit=5):
    db.acknowledge_trigger(t["trigger_id"])
```

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

### Example stats() output

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/yantrikdb-engine/corpus.md

The stats() function returns a dictionary containing counts for various database subsystems.

```python
{"active_memories": 2, "consolidated_memories": 0,
 "tombstoned_memories": 0, "archived_memories": 0,
 "edges": 1, "entities": 2, "operations": 6,
 "open_conflicts": 0, "resolved_conflicts": 0,
 "pending_triggers": 0}
```

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

### Install a pack durably

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/yantrikdb-pack-api/corpus.md

Copy a pack file and record it for automatic re-mounting on future database openings. Use uninstall_pack to reverse this.

```python
pack_id = db.install_pack(pack_path)
db.uninstall_pack(pack_id)
```

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

### Using YantrikDBChatMemory with LangChain

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/adapters.md

Example of initializing YantrikDBChatMemory with a YantrikDB instance, saving context, and loading memory variables.

```python
from yantrikdb import YantrikDB
from yantrikdb.adapters.langchain import YantrikDBChatMemory

db = YantrikDB.with_default("memory.db")
memory = YantrikDBChatMemory(db=db, top_k=5)
memory.save_context({"input": "I prefer dark mode"},
                    {"output": "Noted, dark mode it is."})
loaded = memory.load_memory_variables({"input": "what do I prefer?"})
print(loaded["history"])
```

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

### Configure MCP Client

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/mcp.md

Example configuration for an MCP client like Claude Desktop to run the YantrikDB MCP server.

```json
{
  "mcpServers": {
    "yantrikdb": {
      "command": "python",
      "args": ["-m", "yantrikdb.mcp.server"]
    }
  }
}
```

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

### Handle triggers

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/consolidation.md

Example of checking all triggers and iterating through them to print their attributes.

```python
from yantrikdb.triggers import check_all_triggers

triggers = check_all_triggers(db, importance_threshold=0.7,
                              decay_threshold=0.05, max_triggers=5)
for t in triggers:
    print(t.trigger_type, t.urgency, t.reason, t.suggested_action, t.context)
```

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

### Start and end a YantrikDB session

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/yantrikdb-engine/corpus.md

Demonstrates initializing a session with a namespace and retrieving a summary report upon ending the session.

```python
sid = db.session_start(namespace="ops")
report = db.session_end(sid, "shipped the pack")
# {"session_id": ..., "duration_secs": 0.0009, "memory_count": 0,
#  "avg_valence": 0.0, "topics": []}
```

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

### Manage Sessions and Temporal Queries

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

Demonstrates starting and ending a session to group memory records, as well as querying stale or upcoming memories based on temporal criteria.

```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
```

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

### Common CLI usage examples

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/cli.md

A collection of common operations including setting the database path, recalling information, and managing packs.

```bash
export YANTRIKDB_DB_PATH=~/notes/memory.db
yantrikdb stats
yantrikdb recall "who leads engineering?" -k 5 --json-output
yantrikdb export -o backup.json --no-embeddings
yantrikdb import backup.json --merge
yantrikdb pack keygen
yantrikdb pack sign mypack.ydbpack --key "$SECRET"
```

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

### Configure Alternative Embedder Options

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

Examples for using larger models, custom sentence-transformers, or forcing the bundled offline model.

```python
# Larger still — 512-dim, ~121 MB, downloads on first call.
db = yantrikdb.YantrikDB("memory.db", embedding_dim=512)
db.set_embedder_named("potion-base-32M")

# Bring your own (sentence-transformers, fastembed, custom object).
from sentence_transformers import SentenceTransformer
db = yantrikdb.YantrikDB("memory.db", embedding_dim=384)
db.set_embedder(SentenceTransformer("all-MiniLM-L6-v2"))

# Force the bundled model — no download, works fully offline.
db = yantrikdb.YantrikDB("memory.db", embedding_dim=64)
```

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

### Manage packs via Python API

Source: https://github.com/yantrikos/yantrikdb/blob/main/docs/PACKS.md

Demonstrates transient mounting and durable installation of packs using the YantrikDB Python client.

```python
db = YantrikDB("host.db", 64)                 # bundled embedder, dim 64
db.record_text("I prefer tea over coffee.")

pack_id = db.mount_pack("physics.ydbpack")    # TRANSIENT — refuses on mismatch
db.recall_text("what are gluons")             # ← now answers from the pack
db.unmount_pack(pack_id)                      # host file byte-identical

db.install_pack("physics.ydbpack")            # DURABLE — survives restart
db.installed_packs(); db.mounted_packs()
```

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

### Snapshot operations for peer replication

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/replication-maintenance.md

Example of initializing a database and extracting operations for a peer, including hex-encoding of HLC and embedding hash bytes.

```python
import yantrikdb

db = yantrikdb.YantrikDB.with_default("node-a.db")
db.record("shared fact", domain="work")

# snapshot for a peer
ops = db.extract_ops_since(limit=1000)
serialized = [
    {**op, "hlc": bytes(op["hlc"]).hex(),
     "embedding_hash": bytes(op["embedding_hash"]).hex() if op["embedding_hash"] else None}
    for op in ops
]
```

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

### Example Certificate Output

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

A sample output showing a certified YantrikDB engine build, including held-out set performance and attach-harm regression status.

```text
certified yantrik/yantrikdb-engine@0.1.0
  held-out:    0/8 -> 7/8        (questions the eval author never saw)
  attach-harm: 12 -> 12 / 12  PASS
```

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

### Manage YantrikDB sessions and temporal data

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/sessions-temporal.md

Demonstrates initializing a database, starting and ending a session, recording turns, and querying stale or upcoming data.

```python
import yantrikdb

db = yantrikdb.YantrikDB.with_default("memory.db")
sid = db.session_start("default", "claude-code")
db.record("decided to use PostgreSQL")
db.record_turn("default", "user", "Which DB should we use?")
db.session_end(sid, summary="Chose PostgreSQL")

for m in db.stale(days=14):      # re-surface dormant knowledge
    db.record("reminder: " + m["text"], namespace="default")
for m in db.upcoming(days=7):
    print("deadline approaching:", m["text"])
```

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

### Configure theme.json layout types

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/wordpress-theme/corpus.md

Examples of using flex and grid layout types within WordPress block comments.

```html
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between","flexWrap":"wrap"}} -->
<!-- wp:group {"layout":{"type":"grid","minimumColumnWidth":"16rem"}} -->
```

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

### Define property hooks in PHP 8.4

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/php-modern/corpus.md

Property hooks allow adding validation or transformation logic to public fields without changing the external API. This example demonstrates a computed property with custom get and set logic.

```php
class User {
    public string $fullName {
        get => $this->first . ' ' . $this->last;
        set (string $v) { [$this->first, $this->last] = explode(' ', $v, 2); }
    }
}
```

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

### Define custom settings with camelCase

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/wordpress-theme/corpus.md

Example of using camelCase keys in settings.custom, which are automatically converted to kebab-cased CSS custom properties.

```json
{ "settings": { "custom": {
  "lineHeight": { "tight": 1.1, "body": 1.6 },
  "shadow": { "card": "0 1px 3px rgb(0 0 0 / 0.12)" } } } }
```

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

### Define a color palette preset

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/wordpress-theme/corpus.md

Example of defining a color in the palette, which WordPress automatically converts into a CSS custom property.

```json
{ "settings": { "color": { "palette": [
  { "slug": "primary", "color": "#2f5d50", "name": "Primary" } ] } } }
```

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

### Install YantrikDB MCP package

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

Use this command to install the necessary dependencies for MCP integration.

```bash
pip install yantrikdb[mcp]
```

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

### install_pack(path)

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/packs.md

Copies a pack file beside the database, mounts it, and records it for auto-remounting.

```APIDOC
## install_pack(path)

### Description
Copies a pack file beside the database, mounts it, and records it for auto-remounting.

### Parameters
- **path** (str) - Required - The file system path to the pack file.

### Response
- **Returns** (str) - The pack_id of the installed pack.
```

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

### YantrikDBEntityMemory Usage Example

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/adapters.md

Example demonstrating how to initialize and use the YantrikDBEntityMemory adapter to store and query entity relationships.

```APIDOC
from yantrikdb.adapters.crewai import YantrikDBEntityMemory

# Initialize memory
mem = YantrikDBEntityMemory(db, namespace="crew", top_k=3)

# Save entity relationship
mem.save("Alice leads Engineering",
         metadata={"entity": "Alice", "target_entity": "Engineering",
                   "relationship": "leads"})

# Search memory
for item in mem.search("who runs Engineering?"):
    print(item["context"], round(item["score"], 3))
```

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

### Install YantrikDB MCP

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

Install the YantrikDB MCP package via pip to enable memory management for AI agents.

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

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

### Run Wirecard demonstration

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

Executes the hand-populated Wirecard demonstration using the cargo build tool.

```bash
cargo run --example showcase_wirecard
```

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

### Implement core/media-text feature row

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/wordpress-theme/corpus.md

Use the core/media-text block to create a layout with an image beside text. This example demonstrates a right-aligned media position with vertical centering.

```html
<!-- wp:media-text {"mediaPosition":"right","mediaType":"image","verticalAlignment":"center"} -->
<div class="wp-block-media-text alignwide is-stacked-on-mobile is-vertically-aligned-center has-media-on-the-right">
	<div class="wp-block-media-text__content">
		<!-- wp:heading {"level":3} --><h3 class="wp-block-heading">Measured, not claimed</h3><!-- /wp:heading -->
		<!-- wp:paragraph --><p>Every listing carries the run that produced it.</p><!-- /wp:paragraph -->
	</div>
	<figure class="wp-block-media-text__media"><img alt=""/></figure>
</div>
<!-- /wp:media-text -->
```

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

### Make HTTP GET request with urllib

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/python-stdlib/recipes.md

Performs an HTTP GET request using urllib.request.urlopen. Always specify a timeout as the default is no timeout.

```python
from urllib.request import urlopen, Request
req = Request("https://api.example.com/items",
              headers={"Accept": "application/json"})
with urlopen(req, timeout=10) as resp:
    body = resp.read().decode("utf-8")
```

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

### Initialize and use YantrikDB

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/rust-core.md

Demonstrates initializing the database with a default configuration, recording a new entry, and performing a text recall query.

```rust
use yantrikdb::{YantrikDB, YantrikDbError};

fn main() -> Result<(), YantrikDbError> {
    let db = YantrikDB::with_default("memory.db")?;     // requires bundled-embedder
    let rid = db.record("Alice is the engineering lead", "episodic", 0.8, 0.0,
                        604800.0, &serde_json::json!({}), "default", 0.8,
                        "people", "user", None)?;
    let hits = db.recall_text("who leads the team?", 3)?;
    for h in hits { println!("{} {:.3} {}", h.rid, h.score, h.text); }
    db.close()?;
    Ok(())
}
```

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

### Photo search query examples

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/letterpress/corpus.md

Examples of effective and ineffective search queries for stock images. Use two to four plain nouns to describe objects, places, and materials rather than descriptive sentences or moods.

```text
RIGHT   photo="sourdough bread bakery"
RIGHT   photo="mountain hiking trail"
RIGHT   photo="restaurant interior dining"
WRONG   photo="sourdough loaves cooling on a wooden counter at dawn"
WRONG   photo="warm inviting artisanal atmosphere"
```

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

### Full-bleed group block markup

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/wordpress-theme/corpus.md

Example of a full-bleed group block with a primary background color and vertical padding defined by the spacing scale.

```html
<!-- wp:group {"align":"full","backgroundColor":"primary","style":{"spacing":{"padding":{"top":"var(--wp--preset--spacing--60)","bottom":"var(--wp--preset--spacing--60)"}}},"layout":{"type":"constrained"}} -->
```

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

### get

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/tenant-manager.md

Retrieves or opens a YantrikDB instance for a specific tenant.

```APIDOC
## get(tenant_id: str, embedder: Optional[object]) -> YantrikDB

### Description
Opens or reopens the database file for the specified tenant. Returns a fully-constructed YantrikDB instance.

### Parameters
- **tenant_id** (str) - Required - The ID of the tenant to retrieve.
- **embedder** (object) - Optional - An optional embedder to attach to the database instance.
```

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

### Incorrect PHP usage in HTML template

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/wordpress-theme/corpus.md

Example of invalid PHP code inside an HTML template file, which will be rendered as literal text rather than executed.

```html
<!-- WRONG: .html files are not PHP -->
<a href="<?php echo esc_url( home_url( '/' ) ); ?>">Home</a>
```

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

### Prefixing Shortcodes

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/wordpress-expert/corpus.md

Example of an unprefixed shortcode that risks namespace collision.

```php
add_shortcode('button', …)
```

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

### TenantManager Methods

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/tenant-manager.md

Lists the available methods for registering tenants, retrieving database instances, and listing discovered tenants.

```python
register_tenant(tenant_id, encryption_key=None, embedding_dim=None) -> None
get(tenant_id, embedder=None) -> YantrikDB
discovered_tenants() -> list[str]
```

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

### Error handling

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/rerank.md

Examples of handling ValueError for invalid recall_kwargs and ImportError for missing dependencies.

```python
try:
    recall_reranked(db, "q", pool_k=10, snippets=True)   # rejected
except ValueError as e:
    print("presentation trims belong on the final list:", e)

try:
    rerank_hits("q", hits)   # without the sentence-transformers extra
except ImportError as e:
    print("pip install yantrikdb[sentence-transformers]")
```

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

### Manage packs via CLI

Source: https://github.com/yantrikos/yantrikdb/blob/main/docs/PACKS.md

Commands for inspecting, installing, listing, and removing YantrikDB packs.

```console
$ yantrikdb pack info physics.ydbpack        # read the manifest, install nothing
$ yantrikdb pack install physics.ydbpack     # copies beside the db, mounts, records
$ yantrikdb pack list                        # what is installed, and is it mounted
$ yantrikdb pack remove yantrik/physics@1.0.0
```

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

### Compile and publish a custom pack

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/QUICKSTART.md

A sequence of commands to synthesize, train, evaluate, and bundle a custom pack. This process requires a teacher API, environment configuration, and GPU resources.

```bash
# 1. constitution.md — rules that must hold on every token
# 2. craft.py        — a deterministic checker + brief generators
# 3. synthesise, verified against the checker
python packs/compile.py --pack mypack --synthesize-craft \
    --teacher-api qwen --env-file keys.env --workers 24

# 4. train
.venv-compile/bin/python packs/compile.py --pack mypack-craft --train \
    --base Qwen/Qwen3.5-4B --rank 16 --epochs 20 --quant4 --tag v1

# 5. measure against sealed briefs and a pinned frontier examinee
python packs/evaluate_craft.py --pack mypack --adapter mypack-craft --corpus

# 6. sign and publish
python packs/bundle.py build mypack-craft --tag v1 --key <secret>
```

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

### Import Historical Data with Timestamps

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

Shows how to record memories with specific historical timestamps using created_at and how to perform point-in-time recalls.

```python
db.record("joined the observatory team", created_at=1_600_000_000.0)
db.record_batch([{"text": "...", "created_at": ts} for ts in anchors])

db.recall_as_of(march, query="where do they work")  # what was true then
```

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

### yantrikdb pack subcommands

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/cli.md

Commands for managing packs, including installation, signing, and trust management.

```text
yantrikdb pack info <pack_file>
yantrikdb pack install <pack_file> [--db PATH] [--dim N]
yantrikdb pack list [--db PATH] [--dim N]
yantrikdb pack keygen
yantrikdb pack sign <pack_file> --key SECRET_KEY   # env: YANTRIKDB_PACK_KEY
yantrikdb pack trust <pubkey> [--label TEXT] [--db PATH] [--dim N]
yantrikdb pack remove <pack_id> [--db PATH] [--dim N]
```

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

### Hash strings and files with hashlib

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/python-stdlib/recipes.md

Demonstrates hashing a string and streaming a file using hashlib.sha256 and file_digest.

```python
import hashlib
digest = hashlib.sha256("hello".encode("utf-8")).hexdigest()
with open("wheel.whl", "rb") as f:
    fd = hashlib.file_digest(f, "sha256").hexdigest()
```

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

### Assertion usage

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/c-safety/corpus.md

Example of an incorrect assertion pattern where the side effect vanishes in release builds.

```c
assert(p = malloc(n))
```

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

### Cargo.toml dependencies configuration

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/rust-core.md

Example configuration for adding yantrikdb to your Cargo.toml, including optional features.

```toml
[dependencies]
yantrikdb = { version = "0.7", features = ["embedder-download"] }
# slim: yantrikdb = { version = "0.7", default-features = false }
```

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

### Implement shortcodes with output buffering

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/wordpress-expert/corpus.md

Shortcodes must return content rather than echoing it to ensure correct placement within the content filter. Use ob_start and ob_get_clean to capture output, and shortcode_atts to handle defaults.

```php
add_shortcode('recent_books', function ($atts) { $a =
shortcode_atts(['count' => 5], $atts, 'recent_books'); ob_start(); /* … */
return ob_get_clean(); });
```

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

### Build and Evaluate Packs

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

Use the build script to create sealed .ydbpack files from source directories and the evaluation script to measure model performance improvements.

```bash
python packs/build.py --all                      # source dirs → sealed .ydbpack
python packs/evaluate.py --model qwen3.6:27b     # measure the lift
```

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

### Incorrect fluid typography usage

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/web-craft/corpus.md

An example of a poorly configured clamp() where the floor is too low and the ceiling is arbitrary.

```css
clamp(1rem, 4vw, 3rem)
```

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

### Handling SourceTurnMaintenanceRequiredError

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/graph-cognition.md

Example of catching a maintenance error during thread recall and performing a backfill operation before retrying.

```python
try:
    db.recall_thread_v2("planning", phrases=["ship by"], limit=50)
except yantrikdb.SourceTurnMaintenanceRequiredError:
    while True:
        out = db.maintain_source_turn_backfill(batch=10_000)
        if out["complete"]:
            break
    db.recall_thread_v2("planning", phrases=["ship by"], limit=50)
```

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

### Record and recall operations

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/memory-ops.md

Demonstrates initializing an in-memory database, recording data with idempotency keys, and performing similarity recall.

```python
import yantrikdb

db = yantrikdb.YantrikDB.with_default(":memory:")  # in-memory: bundled 64-dim
rid = db.record("Project deadline is March 30", importance=0.9, domain="work",
                metadata={"key": "deadline"}, created_at=1_700_000_000.0)

# idempotent retry
rid2 = db.record("Project deadline is March 30", importance=0.9,
                 domain="work", idempotency_key="deadline-v1")
assert rid2 == rid  # original rid returned, nothing rewritten

hits = db.recall("when is the deadline?", top_k=3, min_score_ratio=0.2)
for h in hits:
    print(h["rid"], round(h["score"], 3), h["why_retrieved"])
```

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

### Declare strict types

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/php-modern/constitution.md

Every PHP file must start with this statement to enforce strict typing.

```php
declare(strict_types=1);
```

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

### Fluid typography with clamp()

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/web-craft/corpus.md

Example of a fluid heading size that scales between 2.5rem and 4rem based on viewport width.

```css
clamp(2.5rem, 2rem + 3vw, 4rem)
```

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

### Initialize and Use YantrikDB

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/yantrikdb-engine/corpus.md

Create a database, record information, and recall context using the Python library.

```python
import yantrikdb

db = yantrikdb.YantrikDB.with_default("memory.db")

db.record("Alice is the engineering lead", importance=0.8, domain="people")
db.record("Project deadline is March 30", importance=0.9, domain="work")

results = db.recall("who leads the team?", top_k=3)
# -> [{"text": "Alice is the engineering lead", "score": 1.0}, ...]

db.close()
```

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

### Handle IdempotencyConflict

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/memory-ops.md

Example of catching an IdempotencyConflict exception when attempting to record a different payload with an existing idempotency key.

```python
try:
    db.record("dup", idempotency_key="deadline-v1")  # different payload
except yantrikdb.IdempotencyConflict as e:
    print("first write stands:", e)  # carries existing rid
```

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

### Enable appearanceTools in theme.json

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/wordpress-theme/corpus.md

Opt into border, color, spacing, and typography controls using a single flag.

```json
"settings": { "appearanceTools": true }
```

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

### Get pack context for prompts

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/yantrikdb-pack-api/corpus.md

Retrieve a string block describing mounted packs for use in system prompts.

```python
db.pack_context()
```

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

### Configure logging with basicConfig

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/python-stdlib/recipes.md

Use one basicConfig call at the application entry point. Modules should use logging.getLogger(__name__) and avoid manual configuration.

```python
import logging
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s: %(message)s")
log = logging.getLogger(__name__)
log.info("mounted %s in %.1fms", pack, ms)
```

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

### consolidate(db, sim_threshold=0.6, time_window_days=7.0, min_cluster_size=2, limit=100, dry_run=False)

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/consolidation.md

Runs the full consolidation pipeline: clusters similar active memories, writes an extractive synthesis for each cluster, tombstones the sources, and links entities.

```APIDOC
## consolidate(db, sim_threshold=0.6, time_window_days=7.0, min_cluster_size=2, limit=100, dry_run=False)

### Description
Runs the full consolidation pipeline: clusters similar active memories (cosine above sim_threshold, created within time_window_days, cluster >= min_cluster_size, capped at limit), writes an extractive synthesis for each cluster, tombstones the sources, and links entities.

### Parameters
- **db** (YantrikDB) - Required - An open YantrikDB instance.
- **sim_threshold** (float) - Optional - Cosine similarity threshold for clustering.
- **time_window_days** (float) - Optional - Time window in days for clustering.
- **min_cluster_size** (int) - Optional - Minimum number of memories to form a cluster.
- **limit** (int) - Optional - Maximum number of clusters to process.
- **dry_run** (bool) - Optional - If True, previews without writing.

### Response
- **list[dict]** - Returns a list of ConsolidationResult-shaped dicts.
```

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

### Publishing and signing a pack

Source: https://github.com/yantrikos/yantrikdb/blob/main/_autodocs/api-reference/packs.md

Workflow for generating keypairs, trusting a publisher, and signing a pack for distribution.

```python
secret, public = yantrikdb.YantrikDB.generate_pack_keypair()
key = yantrikdb.YantrikDB.pubkey_of(secret)
db.trust_publisher(key, label="acme-publisher")
pub = yantrikdb.YantrikDB.sign_pack("compendium.ydbpack", secret)
assert yantrikdb.YantrikDB.verify_bytes(pub, b"hello", yantrikdb.YantrikDB.sign_bytes(secret, b"hello"))
```

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

### Define relational checks in packs/relations.py

Source: https://github.com/yantrikos/yantrikdb/blob/main/packs/CAPABILITIES.md

Examples of relational checks including formula expressions, ratio ranges, and contrast minimums.

```json
{"path": "jump.gravity", "test": "formula",
 "args": {"expr": "2*h/(t/1000)**2",
          "vars": {"h": "jump.height_px", "t": "jump.time_ms"}, "tol": 0.03}}

{"path": "jump.fall_gravity", "test": "ratio_range",
 "args": {"of": "jump.gravity", "min": 1.25, "max": 3.0}}

{"path": "palette.ui_text", "test": "contrast_min",
 "args": {"against": "palette.bg", "min": 4.5}}
```
Tokens:
Raw