Initialization
from lyzr import Cognis
# Default — connects to production
cog = Cognis(api_key="sk-your-api-key")
# With custom timeout
cog = Cognis(api_key="sk-your-api-key", timeout=60)
# With environment selection
cog = Cognis(api_key="sk-your-api-key", env="dev")
| Parameter | Type | Default | Description |
|---|
api_key | str | $LYZR_API_KEY | Lyzr API key |
env | str | ServiceURLs | "prod" | Environment: "prod", "dev", "local", or custom |
timeout | int | 30 | Request timeout in seconds |
from cognis import Cognis
# Basic — at least one of owner_id/agent_id/session_id required
m = Cognis(owner_id="user_1")
# With custom data directory
m = Cognis(owner_id="user_1", data_dir="./my_data")
# With explicit API key
m = Cognis(owner_id="user_1", gemini_api_key="your-gemini-key")
| Parameter | Type | Default | Description |
|---|
gemini_api_key | str | $GEMINI_API_KEY or $GOOGLE_API_KEY | Gemini API key for embeddings |
owner_id | str | — | Memory owner identifier |
agent_id | str | None | Agent identifier |
session_id | str | Auto-generated | Session identifier |
data_dir | str | ~/.cognis | Local storage directory |
config | CognisConfig | Defaults | Configuration overrides |
Multi-Tenant Scoping
Every Cognis operation uses scoping identifiers to isolate memories. This works the same in both versions.
| Identifier | Purpose | Example |
|---|
owner_id | Scope to a user/tenant | "user_alice" |
agent_id | Scope to an agent | "support_bot" |
session_id | Scope to a conversation | "sess_abc123" |
At least one of owner_id, agent_id, or session_id must be provided for every operation.
# User-scoped memories (across all sessions)
cog.add(messages=msgs, owner_id="user_alice")
# Session-scoped memories
cog.add(messages=msgs, owner_id="user_alice", session_id="sess_1")
# Agent-specific memories
cog.add(messages=msgs, agent_id="support_bot", owner_id="user_alice")
Search Tuning (Open Source)
The open-source version exposes CognisConfig for fine-grained search tuning. These defaults were optimized from ablation studies on the LoCoMo benchmark.
from cognis import Cognis, CognisConfig
config = CognisConfig(
# RRF fusion weights
vector_weight=0.70, # 70% vector search
bm25_weight=0.30, # 30% keyword search
rrf_k=10, # RRF constant
similarity_threshold=0.3, # Minimum score to include
# Recency
recency_boost_weight=0.25,
recency_half_life_seconds=120.0,
# Models
embedding_model="gemini/gemini-embedding-2-preview",
llm_model="gpt-4.1-mini", # For fact extraction
# Embedding dimensions (Matryoshka)
embedding_full_dim=768, # Full precision reranking
embedding_small_dim=256, # Fast candidate shortlisting
)
m = Cognis(config=config, owner_id="user_1")
Full CognisConfig Reference
| Field | Default | Description |
|---|
vector_weight | 0.70 | Weight for vector search in RRF fusion |
bm25_weight | 0.30 | Weight for BM25 keyword search |
rrf_k | 10 | RRF constant (higher = smoother rank distribution) |
similarity_threshold | 0.3 | Minimum similarity to include results |
shortlist_size | 200 | 256D candidates before 768D reranking |
recency_boost_weight | 0.25 | Recency boost strength |
recency_half_life_seconds | 120.0 | Recency decay half-life |
enable_temporal_decay | True | Time-based relevance decay |
enable_temporal_query_detection | True | Detect “last week”, “yesterday” queries |
embedding_model | "gemini/gemini-embedding-2-preview" | Embedding model via LiteLLM |
embedding_full_dim | 768 | Full-dimension embedding size |
embedding_small_dim | 256 | Shortlist embedding size |
llm_model | "gpt-4.1-mini" | LLM for fact extraction |
update_similarity_threshold | 0.85 | Threshold for updating vs creating new memory |
add_similarity_threshold | 0.70 | Threshold below which new memory is always created |
enable_immediate_recall | True | 256D vector index for raw messages |
immediate_recall_ttl_hours | 48 | TTL for immediate recall entries |
Custom Categories
Override the default 13 categories:
config = CognisConfig(
categories={
"product_feedback": "User feedback about products and features",
"support_issues": "Technical issues and bug reports",
"preferences": "User preferences and settings",
}
)
