Quickstart

Install Cognis and run your first memory operations in 3 minutes.

Prerequisites

• Python 3.8 or later.
• A Lyzr API key for the hosted version, or API keys for Gemini (embeddings) and OpenAI (fact extraction) for the open-source version.

1. Install

Hosted (lyzr-adk)

pip install lyzr-adk

Open Source (lyzr-cognis)

pip install lyzr-cognis

2. Set API keys

Hosted (lyzr-adk)

export LYZR_API_KEY="your-lyzr-api-key"

Open Source (lyzr-cognis)

export GEMINI_API_KEY="your-gemini-key"
export OPENAI_API_KEY="your-openai-key"

3. Add memories

Send conversation messages to Cognis. It extracts and stores discrete facts automatically.

Hosted (lyzr-adk)

from lyzr import Cognis, CognisMessage

cog = Cognis(api_key="sk-your-api-key")

cog.add(
    messages=[
        CognisMessage(role="user", content="My name is Alice. I love hiking and I'm vegetarian."),
        CognisMessage(role="assistant", content="Nice to meet you, Alice!"),
    ],
    owner_id="user_alice",
)

Open Source (lyzr-cognis)

from cognis import Cognis

m = Cognis(owner_id="user_alice")

result = m.add([
    {"role": "user", "content": "My name is Alice. I love hiking and I'm vegetarian."},
    {"role": "assistant", "content": "Nice to meet you, Alice!"},
])
print(result["message"])
# "Extracted 3 memories from 2 messages"

4. Search memories

Retrieve the most relevant facts before your agent responds.

Hosted (lyzr-adk)

results = cog.search(query="What does Alice eat?", owner_id="user_alice", limit=5)
for r in results:
    print(f"{r.content}  (score: {r.score})")
# "Alice is vegetarian  (score: 0.89)"

Open Source (lyzr-cognis)

resp = m.search("What does Alice eat?", limit=5)
for r in resp["results"]:
    print(f"{r['content']}  (score: {r['score']})")
# "Alice is vegetarian  (score: 0.8712)"

5. Get context for your LLM

Assemble both short-term conversation history and long-term memories into a single string for your system prompt.

Hosted (lyzr-adk)

context = cog.context(
    current_messages=[CognisMessage(role="user", content="Recommend a restaurant")],
    owner_id="user_alice",
)
# Pass context into your LLM system prompt

Open Source (lyzr-cognis)

ctx = m.get_context(
    messages=[{"role": "user", "content": "Recommend a restaurant"}]
)
print(ctx["context_string"])
# "Relevant memories:\n- Alice is vegetarian\n- ..."

m.close()  # Required for the OSS client

What just happened

Cognis stored your raw messages, then the extraction layer pulled discrete facts and auto-categorized them (identity, preferences, interests, and more). Each fact was embedded and indexed for hybrid search using 70% vector similarity and 30% BM25 keyword matching. The context / get_context call assembled both short-term messages and long-term memories into a ready-to-use LLM context string.

Next steps

• Memory types: understand session, long-term, and cross-session scoping.
• Add Memories reference: full parameter and response documentation.
• Search Memories reference: scoring, filtering, and limit options.