> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyzr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cognis

> Memory layer for AI agents. Store facts, preferences, and context from conversations and retrieve them across sessions.

Cognis is Lyzr's memory layer for AI agents. It lets agents remember things across conversations: user preferences, past decisions, resolved issues, and facts extracted from prior sessions.

Without Cognis, every conversation starts blank. A user who told your agent they are vegetarian has to say so again next time. A support agent that resolved a billing issue has no memory of it when the same user returns. Cognis closes that gap.

## How it works

1. Your agent sends conversation messages (user and assistant turns) to Cognis.
2. Cognis extracts discrete facts automatically using LLM-powered extraction with auto-categorization.
3. Before responding, your agent searches Cognis. The most relevant facts are returned using hybrid search (vector similarity plus BM25 keyword matching, fused with Reciprocal Rank Fusion).
4. Memories persist across sessions, scoped by `owner_id`, `agent_id`, and `session_id`.

> 🖼️ **VISUAL, Diagram, high priority**
> **Show:** the four-step flow: agent sends messages to Cognis, Cognis extracts facts, agent queries Cognis before responding, facts returned to agent context.
> **Why it helps:** the add/search loop is the core usage pattern and is easier to follow as a diagram than prose.
> **Alt text:** Diagram showing the Cognis memory loop: messages flow into Cognis for extraction, then the agent queries Cognis and receives relevant memories before generating a response.

## Core capabilities

Cognis provides hybrid search using Matryoshka vector embeddings and BM25 keyword matching, fused with Reciprocal Rank Fusion for relevance ranking. The LLM extraction layer automatically pulls discrete facts from conversations and categorizes them by type (identity, preferences, work context, interests, and more). Memory records are scoped with `owner_id`, `agent_id`, and `session_id` identifiers so the right context reaches the right agent for the right user. The context assembly method combines short-term conversation history with long-term memories into a single LLM-ready string.

## Quick example

<Tabs>
  <Tab title="Hosted (lyzr-adk)">
    ```python theme={null}
    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'm vegetarian and love hiking."),
            CognisMessage(role="assistant", content="Nice to meet you, Alice!"),
        ],
        owner_id="user_alice",
    )

    results = cog.search(query="food preferences", owner_id="user_alice")
    for r in results:
        print(r.content)
    # "Alice is vegetarian"
    ```
  </Tab>

  <Tab title="Open Source (lyzr-cognis)">
    ```python theme={null}
    from cognis import Cognis

    m = Cognis(owner_id="user_alice")

    m.add([
        {"role": "user", "content": "My name is Alice. I'm vegetarian and love hiking."},
        {"role": "assistant", "content": "Nice to meet you, Alice!"},
    ])

    resp = m.search("food preferences")
    for r in resp["results"]:
        print(r["content"])
    # "Alice is vegetarian"

    m.close()
    ```
  </Tab>
</Tabs>

Cognis is available as a hosted API via `pip install lyzr-adk` and as an open-source library via `pip install lyzr-cognis`. The core extraction and search architecture is the same in both.

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="./quickstart">
    Install Cognis and run your first memory operations in 3 minutes.
  </Card>

  <Card title="Memory types" icon="layer-group" href="./memory-types">
    Understand session, long-term, and cross-session memory scoping.
  </Card>

  <Card title="Add Memories" icon="plus" href="./api/add-memories">
    Full method reference for storing conversations.
  </Card>

  <Card title="Search Memories" icon="magnifying-glass" href="./api/search-memories">
    Retrieve relevant facts before your agent responds.
  </Card>
</CardGroup>