velixar 0.1.0

Persistent memory infrastructure for AI applications

Velixar Python SDK

Persistent memory infrastructure for AI applications.

Installation

pip install velixar

# With LangChain integration
pip install velixar[langchain]

# With LlamaIndex integration
pip install velixar[llamaindex]

# All integrations
pip install velixar[all]

Quick Start

from velixar import Velixar

# Initialize client
v = Velixar(api_key="vlx_your_key")  # Or set VELIXAR_API_KEY env var

# Store a memory
memory_id = v.store(
    content="User prefers dark mode and metric units",
    tier=0,  # 0=pinned (critical), 2=semantic (default)
    user_id="user_123",
    tags=["preferences", "settings"],
)

# Search memories
results = v.search("user preferences", limit=5)
for memory in results.memories:
    print(f"[{memory.score:.2f}] {memory.content}")

# Get context for LLM prompts
context = v.get_context("What are the user's preferences?", max_tokens=2000)

Async Support

from velixar import AsyncVelixar

async with AsyncVelixar(api_key="vlx_...") as v:
    await v.store("User's favorite color is blue", user_id="user_123")
    results = await v.search("favorite color")

Memory Tiers

Tier	Name	Use Case
0	Pinned	Critical facts, user preferences, never expire
1	Session	Current conversation context
2	Semantic	Long-term memories (default)
3	Organization	Shared team knowledge

from velixar import MemoryTier

# Store critical preference
v.store("User is allergic to peanuts", tier=MemoryTier.PINNED)

# Store session context
v.store("Currently discussing project X", tier=MemoryTier.SESSION)

LangChain Integration

from langchain.chains import ConversationChain
from langchain_openai import ChatOpenAI
from velixar.integrations.langchain import VelixarMemory

# Create memory backed by Velixar
memory = VelixarMemory(
    api_key="vlx_...",
    user_id="user_123",
)

# Use with any LangChain chain
chain = ConversationChain(
    llm=ChatOpenAI(),
    memory=memory,
)

response = chain.invoke({"input": "Remember that I prefer Python over JavaScript"})
response = chain.invoke({"input": "What programming language do I prefer?"})

LlamaIndex Integration

from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI
from velixar.integrations.llamaindex import VelixarMemory

memory = VelixarMemory(api_key="vlx_...", user_id="user_123")

agent = ReActAgent.from_tools(
    tools=[...],
    llm=OpenAI(),
    memory=memory,
)

OpenAI Function Calling

from openai import OpenAI
from velixar import Velixar
from velixar.integrations.openai import VelixarAssistant

# Simple wrapper with automatic memory
assistant = VelixarAssistant(
    openai_client=OpenAI(),
    velixar_api_key="vlx_...",
    user_id="user_123",
)

assistant.chat("Remember that my birthday is March 15th")
assistant.chat("When is my birthday?")  # Uses memory automatically

Batch Operations

# Store multiple memories at once
result = v.store_many([
    {"content": "Fact 1", "tier": 0},
    {"content": "Fact 2", "tier": 2, "tags": ["important"]},
    {"content": "Fact 3", "user_id": "user_456"},
])
print(f"Stored {result.stored} memories")

Error Handling

from velixar import Velixar, VelixarError, RateLimitError, AuthenticationError

try:
    v = Velixar(api_key="invalid")
    v.store("test")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except VelixarError as e:
    print(f"Error: {e.message}")

Configuration

v = Velixar(
    api_key="vlx_...",           # Or VELIXAR_API_KEY env var
    base_url="https://...",      # Custom endpoint (optional)
    timeout=30.0,                # Request timeout in seconds
    max_retries=3,               # Retry attempts for failures
)

Environment Variables

Variable	Description
VELIXAR_API_KEY	Your API key
VELIXAR_BASE_URL	Custom API endpoint

License

MIT License - see LICENSE for details.