Cognis is Lyzr’s standalone memory client that gives you direct CRUD access to the memory service. Unlike agent-level memory (setting memory=30 on agents), Cognis lets you programmatically add, search, retrieve, update, and delete memories — ideal for building custom memory workflows, multi-agent systems, and user-scoped memory stores.
Installation
Quick Start
from lyzr import Cognis
# Initialize the client
cog = Cognis(api_key="sk-your-api-key")
# Store a conversation
cog.add(
messages=[
{"role": "user", "content": "My name is Alice and I love Python."},
{"role": "assistant", "content": "Nice to meet you, Alice!"},
],
owner_id="user_alice",
)
# Search memories
results = cog.search(query="What is the user's name?", owner_id="user_alice")
for result in results:
print(result.content, result.score)
# Retrieve all memories
memories = cog.get(owner_id="user_alice")
for memory in memories:
print(memory.id, memory.content)
How It Works
- Add messages — You send conversation messages (user/assistant pairs) to Cognis via
cog.add().
- Memory extraction — The service automatically extracts key facts and preferences from the conversation into discrete memory records.
- Semantic search — When you call
cog.search(), the query is matched against stored memories using semantic similarity, returning the most relevant results with relevance scores.
- Full CRUD — You can retrieve, update, and delete individual memory records by ID.
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")
Constructor Parameters
| Parameter | Type | Required | Description |
|---|
api_key | str | No | Lyzr API key. Falls back to LYZR_API_KEY env var. |
env | str | ServiceURLs | No | Environment: "prod" (default), "dev", "local", or a custom ServiceURLs instance. |
timeout | int | No | Request timeout in seconds. Default: 30. |
Multi-Tenant Scoping
Every Cognis operation requires at least one scoping identifier. These identifiers control which memories are stored and retrieved:
| Identifier | Purpose | Example |
|---|
owner_id | Scope memories to a specific user/tenant | "user_alice" |
agent_id | Scope memories to a specific agent | "support_agent" |
session_id | Scope memories to a conversation session | "sess_abc123" |
# 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")
At least one of owner_id, agent_id, or session_id must be provided for every operation. A ValueError is raised if none are specified.
Sync and Async
Cognis supports both synchronous and asynchronous usage. Every sync method has an async counterpart prefixed with a:
| Sync | Async |
|---|
cog.add() | cog.aadd() |
cog.search() | cog.asearch() |
cog.get() | cog.aget() |
cog.get_memory() | cog.aget_memory() |
cog.update() | cog.aupdate() |
cog.delete() | cog.adelete() |
Async Usage
import asyncio
from lyzr import Cognis
async def main():
async with Cognis(api_key="sk-your-api-key") as cog:
await cog.aadd(
messages=[{"role": "user", "content": "Hello!"}],
owner_id="user_1",
)
results = await cog.asearch(query="greeting", owner_id="user_1")
print(results)
asyncio.run(main())
Context Manager
Cognis supports both sync and async context managers for proper resource cleanup:
# Sync
with Cognis(api_key="sk-your-api-key") as cog:
cog.add(messages=msgs, owner_id="user_1")
# Async
async with Cognis(api_key="sk-your-api-key") as cog:
await cog.aadd(messages=msgs, owner_id="user_1")
Operations
