From Zero to Query in 60 Seconds

# 1. Create and activate a virtual environment
python -m venv venv

# Windows PowerShell:
.\venv\Scripts\Activate.ps1

# Linux / macOS:
source venv/bin/activate

# 2. Install TapirusDB
pip install tapirus

from tapirus import Tapirus

# Open or create encrypted single-file container
with Tapirus.open("app.tapir") as db:
    # 1. Execute SQL Transaction
    db.execute("CREATE TABLE IF NOT EXISTS agents (id INTEGER PRIMARY KEY, name TEXT, role TEXT);")
    db.execute("INSERT INTO agents VALUES (1, 'Hermes', 'Autonomous Researcher');")
    db.execute("INSERT INTO agents VALUES (2, 'Argus', 'Telemetry Monitor');")

    # 2. Query as native Python dictionaries
    results = db.query("SELECT * FROM agents;")
    print("Database Records:", results)

    # 3. Vector Similarity Search
    db.execute("CREATE TABLE embeddings (doc_id INT PRIMARY KEY, title TEXT, vector VECTOR(4));")
    db.execute("INSERT INTO embeddings VALUES (1, 'Sovereign AI', [0.12, 0.45, 0.88, -0.23]);")
    
    matches = db.query("SELECT doc_id, title FROM embeddings ORDER BY VECTOR_COSINE(vector, [0.10, 0.40, 0.85, -0.20]) DESC LIMIT 1;")
    print("Nearest Vector Match:", matches)

python app.py

cargo new tapirus_quickstart
cd tapirus_quickstart
cargo add tapirus

use tapirus::{Connection, Result};

fn main() -> Result<()> {
    // Open single-file container (or Connection::open_in_memory()?)
    let db = Connection::open("production.tapir")?;

    // Relational SQL with native 4D Vector
    db.execute("
        CREATE TABLE IF NOT EXISTS memory (
            id INTEGER PRIMARY KEY,
            content TEXT NOT NULL,
            embedding VECTOR(4)
        );
    ")?;

    db.execute("
        INSERT INTO memory VALUES (1, 'Safe Rust Architecture', [0.12, 0.45, 0.88, -0.23]);
    ")?;

    let rows = db.query("SELECT id, content FROM memory WHERE id = 1;")?;
    println!("Retrieved Row: {:?}", rows);

    Ok(())
}

cargo run

mkdir go-tapirus && cd go-tapirus
go mod init myapp
go get github.com/tapiruslab/TapirusDB/sdks/go

package main

import (
	"context"
	"fmt"
	tapirus "github.com/tapiruslab/TapirusDB/sdks/go"
)

func main() {
	client := tapirus.NewClient(tapirus.Config{
		Endpoint: "http://127.0.0.1:8080",
	})

	ctx := context.Background()

	// Query SQL
	res, err := client.Query(ctx, "SELECT id, name FROM items;")
	if err != nil {
		panic(err)
	}
	fmt.Println("Result:", res)
}

go run main.go

┌─────────────────────────────────────────────────────────────────┐
│                  Autonomous AI Agent Runtime                    │
└────────────────────────────────┬────────────────────────────────┘
                                 │ Direct In-Process C-ABI / SDK (< 0.02 ms)
┌────────────────────────────────▼────────────────────────────────┐
│               TapirusDB Embedded Engine (< 4MB RAM)             │
│  1. Relational & Window Analytics  (Turn ranking, LAG/LEAD)     │
│  2. Native SIMD Vector Index       (Cosine, L2 Top-K Search)    │
│  3. GraphBLAS Topological Engine   (Louvain, Centrality, WCC)   │
└────────────────────────────────┬────────────────────────────────┘
                                 │ Single Encrypted File: `agent_vault.tapir`

import tapirus
import time
from typing import List, Dict, Any

class AgentMemory:
    def __init__(self, vault_path: str = "agent_vault.tapir"):
        # Open local encrypted or plaintext vault (or ":memory:")
        self.conn = tapirus.connect(vault_path)
        self._init_schema()

    def _init_schema(self):
        # 1. Episodic Dialogue & Tool Log
        self.conn.execute("""
            CREATE TABLE IF NOT EXISTS episodes (
                id INTEGER PRIMARY KEY,
                session_id TEXT,
                step INTEGER,
                role TEXT,
                content TEXT,
                embedding VECTOR(4)
            );
        """)

        # 2. Knowledge Graph Associative Relationships
        self.conn.execute("""
            CREATE TABLE IF NOT EXISTS kg_edges (
                src_entity TEXT,
                dst_entity TEXT,
                relation TEXT,
                weight FLOAT
            );
        """)

    def record_episode(self, session_id: str, step: int, role: str, content: str, embedding: List[float]):
        """Records an episodic conversational turn or tool action with embedding."""
        clean_content = content.replace("'", "''")
        self.conn.execute(f"""
            INSERT INTO episodes (id, session_id, step, role, content, embedding)
            VALUES ({int(time.time()*1000)}, '{session_id}', {step}, '{role}', '{clean_content}', {embedding});
        """)

    def get_conversation_flow(self, session_id: str) -> List[Dict[str, Any]]:
        """
        Uses ANSI SQL Window Functions (LAG) to fetch the interaction flow 
        along with what the previous turn said in a single sub-millisecond query.
        """
        sql = f"""
            SELECT 
                step, 
                role, 
                content,
                LAG(content, 1) OVER (PARTITION BY session_id ORDER BY step ASC) as previous_turn
            FROM episodes 
            WHERE session_id = '{session_id}'
            ORDER BY step ASC;
        """
        return self.conn.query(sql)

    def retrieve_similar_episodes(self, query_embedding: List[float], top_k: int = 3) -> List[Dict[str, Any]]:
        """Performs native SIMD Cosine similarity search across all historical episodes."""
        return self.conn.vector_search("episodes", "embedding", query_embedding, top_k=top_k)

    def add_knowledge_link(self, src: str, dst: str, relation: str, weight: float = 1.0):
        """Adds an associative knowledge link between two extracted entities."""
        self.conn.execute(f"""
            INSERT INTO kg_edges VALUES ('{src}', '{dst}', '{relation}', {weight});
        """)

    def detect_topic_clusters(self) -> Dict[str, Any]:
        """Runs native Louvain community modularity algorithm on the agent's knowledge graph."""
        return self.conn.graph_algorithm("louvain")

    def checkpoint(self):
        """Flushes WAL log frames to the main .tapir container file."""
        return self.conn.checkpoint()

# Example Execution:
if __name__ == "__main__":
    memory = AgentMemory(":memory:")
    
    # Ingest episodes
    memory.record_episode("sess_01", 1, "user", "What is the capital of Malaysia?", [0.1, 0.8, 0.4, 0.2])
    memory.record_episode("sess_01", 2, "assistant", "The capital of Malaysia is Kuala Lumpur.", [0.12, 0.79, 0.41, 0.22])
    
    # Query with window function
    flow = memory.get_conversation_flow("sess_01")
    print("Episodic flow with LAG analysis:", flow)
    
    # Semantic search
    matches = memory.retrieve_similar_episodes([0.11, 0.81, 0.39, 0.21], top_k=2)
    print("Semantic matches:", matches)

import { TapirusClient, open } from "tapirusdb";

async function runAgentMemory() {
  const db = new TapirusClient({ dbPath: "agent_memory.tapir" });

  // 1. Initialize schema
  await db.execute(`
    CREATE TABLE agent_turns (
      id INTEGER PRIMARY KEY,
      turn_index INTEGER,
      speaker TEXT,
      utterance TEXT,
      features VECTOR(4)
    );
  `);

  // 2. Ingest interaction with dense vector
  await db.execute(`
    INSERT INTO agent_turns VALUES (
      1, 1, 'user', 'Analyze quarterly revenue drop', [0.85, 0.12, 0.45, 0.90]
    );
  `);

  // 3. Analytics with SQL Window Functions
  const rankedTurns = await db.query(`
    SELECT turn_index, speaker, 
           ROW_NUMBER() OVER (ORDER BY turn_index ASC) as sequential_rank 
    FROM agent_turns;
  `);
  console.log("Ranked agent turns:", rankedTurns);

  // 4. Built-in SIMD Vector Search
  const matches = await db.vectorSearch("agent_turns", "features", [0.82, 0.15, 0.40, 0.88], 3);
  console.log("Vector semantic matches:", matches);
}

runAgentMemory().catch(console.error);