Chapter 01

Core Architecture & Concepts

OpenYantra bridges local storage and active AI agent memory. It uses Sanskrit terminology to define structural concepts designed for 100% data ownership, cryptographic tracking, and seamless cross-session recall.

Sanskrit Terminology & Definitions

01

यन्त्र (Yantra)

The physical system container and state runtime coordinating fast local memory pipelines.

02

चित्रपट (Chitrapat)

The canonical open-standard ODS file representing the entire relational ledger structure.

03

चित्रगुप्त (Chitragupta)

The secure Ledger Agent who enforces read/write schemas, validates parameters, and signs transactions.

04

सञ्चित (Sanchitta)

The local SQLite database storing the Write-Ahead Log (WAL) operational source of truth.

05

प्रतिबिम्ब (Pratibimba)

The contextual prompt reflection dynamically injected into active agent session systems.

06

विद्याकोश (VidyaKosha)

The dense embeddings engine supplying fast semantic memory searches without cloud APIs.

The 14-Sheet Canonical Schema

Every Chitrapat contains 14 standardized relational sheets. This structure enforces semantic separation between goals, current tasks, preferences, and security logging.

Sheet Name	Sanskrit Context	Primary Functionality
👤 Identity	Pratyabhijñā (प्रत्यभिज्ञा)	Contains core attributes, occupations, and location contexts of the user.
🎯 Goals	Sankalpa (सङ्कल्प)	Tracks active high-level targets, deadlines, and deadlines.
🚀 Projects	Kārya (कार्य)	Monitors active domains, key steps, status state, and update history.
🧠 Beliefs	Siddhānta (सिद्धान्त)	Stores core principles, positions, and automatically flagged contradictions.
🔓 Open Loops	Apūrva (अपूर्व)	Tracks unresolved issues, topic scopes, and Time-To-Live (TTL) durations.
📒 Ledger	Agrasandhanī (अग्रसन्धानी)	The cryptographically signed transaction history logs.
🛡️ Security Log	Rakshana (रक्षण)	Logs active agent access, system state checks, and threat mitigation.

Chapter 02

Quick Start & Installation

Deploy OpenYantra to your local development workspace in seconds using the automated one-command script or a manual python pip setup.

Automated Installation

For macOS and Linux systems (Bash):

macOS / Linux install

$ curl -sSL https://raw.githubusercontent.com/revanthlevaka/OpenYantra/main/install.sh | bash

For Windows systems (PowerShell):

Windows install

PS> irm https://raw.githubusercontent.com/revanthlevaka/OpenYantra/main/install.ps1 | iex

Manual Python Installation

If you prefer managing dependencies manually, ensure you have Python 3.9+ installed and run:

Manual Pip Install

$ pip install openyantra
$ pip install odfpy pandas scikit-learn faiss-cpu fastapi uvicorn portalocker

Initial Bootstrapping

After installing OpenYantra, initialize your sacred memory files and build the default relational spreadsheet configuration by running:
yantra bootstrap

Chapter 03

CLI Reference & Workflows

Command-line tools are the direct channel to read, write, sync, and check the health of your local cognitive space.

Interactive CLI Workflow Commands

The Daily Briefing Workflow

Start each development day by triggering your morning dashboard preview. This loads active goals, checks for stale projects (no edits in 7 days), and summarizes unrouted inbox items:

yantra morning

$ yantra morning

========================================================
  Good morning, User. OpenYantra v4.1.0
  2026-05-21
========================================================
  🔓  Open Loops (3 total):
     [High    ] finalize Passkey authentication workflow
     [Medium  ] resolve UI transition stutter on docs page
  
  🚀  Stale Projects:
     openyantra-core -- no update in 9 days
       -> audit yantra_migrate schema constraints
  
  📥  Inbox: 5 items unrouted
  
  🔥  Streak: 12 days
--------------------------------------------------------
  yantra ui -> http://localhost:7331
========================================================

Chapter 04

Model Context Protocol (MCP) Server

Hook OpenYantra directly into your IDE (Cursor, Claude Desktop, Cline, and more) as a standard MCP Server. This allows models to autonomously retrieve context and log new loops.

MCP Core Tools Exposed

Tool Name	Arguments	Usage Context
get_identity	None	Returns user profile characteristics, occupation, and name preferences.
get_active_projects	None	Lists all current high-level project targets with next steps.
get_open_loops	`top_k: int` (default 15)	Fetches unresolved topics categorized by priority and deadline.
add_inbox_item	`content: str`, `importance: int`	Injects a quick thought or item for automated routing.
add_open_loop	`topic: str`, `context: str`, `priority: str`	Registers a new unresolved loop directly to the database.

Client Configurations

1. Claude Desktop: Add this block to your local configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

claude_desktop_config.json

{
  "mcpServers": {
    "openyantra": {
      "command": "yantra",
      "args": ["mcp"]
    }
  }
}

2. Cursor IDE: Navigate to Settings > Models > MCP > Add New MCP. Select command as Type, and configure as follows:

Name	`openyantra`
Type	`command`
Command	`yantra mcp` (or `npx -y openyantra@latest mcp`)

3. Cline & Continue: Typical config blocks for system environments:

cline_mcp_settings.json

{
  "mcpServers": {
    "openyantra": {
      "command": "uvx",
      "args": ["openyantra", "mcp"],
      "disabled": false
    }
  }
}

Chapter 05

API & Framework Integration

Integrate OpenYantra inside your custom Python agents, pipelines, and frameworks. This maintains persistent long-term memory sessions.

Raw Anthropic/OpenAI SDK hookups

python message injection

# Ingest memory reflections directly into messages context
from openyantra import OpenYantra

oy = OpenYantra("~/openyantra/chitrapat.ods", agent_name="CoreAssistant")
oy.take_pratibimba()

# Build system instructions from Chitrapat config and preferences
system_prompt = oy.build_system_prompt_block()

# Perform semantic search on memory
results = oy.search("user preference on design colors")
# ... send system_prompt + results to LLM API ...

# Finalize session and write log
oy.log_session(topics=["docs-update"])
oy.release_pratibimba()

LangChain Adapters

langchain_adapter.py

from openyantra.examples.langchain_adapter import OpenYantraChatMemory
from langchain.agents import initialize_agent

memory = OpenYantraChatMemory(path="~/openyantra/chitrapat.ods", agent_name="LangAgent")
agent  = initialize_agent(tools=[], llm=llm, memory=memory)

Chapter 06

Security & Local Encryption

OpenYantra takes a zero-compromise approach to lock authorization, security logging, and concurrent write safety.

Local Biometric Passkey (v4.1.0+)

v4.1.0 introduces WebAuthn local biometric verification. Using Windows Hello or Apple TouchID/FaceID, developers can secure local SQLite datastores and configuration ledgers against unauthorized terminal execution.

Apple/Windows Biometrics

# Local biometric verification flow
from openyantra.yantra_passkey import PasskeyAuth

# Trigger biometric prompt window
auth_ok = PasskeyAuth.authenticate()
if not auth_ok:
    print("Biometric verification failed. Aborting write.")
    sys.exit(1)

Concurrent Lock Control

Writing to spreadsheets from multiple parallel agent execution blocks frequently corrupts indices. OpenYantra employs a portalocker system block that intercepts writes, locks targets, processes transactional updates to SQLite WAL first, and then releases resources atomically.