Add Memories

Store conversation messages in Cognis. Facts and preferences are extracted and indexed automatically.

The add method stores conversation messages in Cognis memory. The extraction layer automatically pulls discrete facts, preferences, and context from the messages and indexes them as searchable memory records.

Method signature

cog.add(
    messages: List[Dict[str, str] | CognisMessage],
    owner_id: str | None = None,
    agent_id: str | None = None,
    session_id: str | None = None,
) -> Dict[str, Any]

At least one of owner_id, agent_id, or session_id must be provided.

Parameters

Parameter	Type	Required	Description
messages	List[Dict[str, str] | CognisMessage]	Yes	Conversation messages. Each message must have role ("user" or "assistant") and content keys.
owner_id	str	Conditional	User or owner identifier for memory scoping.
agent_id	str	Conditional	Agent identifier for memory scoping.
session_id	str	Conditional	Session identifier for memory scoping.

Response

{
  "success": true,
  "session_id": "sess_abc123",
  "memories_created": 2
}

Basic usage

Hosted (lyzr-adk)

from lyzr import Cognis

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

result = cog.add(
    messages=[
        {"role": "user", "content": "My name is Alice and I work at Acme Corp."},
        {"role": "assistant", "content": "Nice to meet you, Alice!"},
    ],
    owner_id="user_alice",
)
print(result)
# {"success": True, "session_id": "...", "memories_created": 2}

Open Source (lyzr-cognis)

from cognis import Cognis

m = Cognis(owner_id="user_alice")

result = m.add([
    {"role": "user", "content": "My name is Alice and I work at Acme Corp."},
    {"role": "assistant", "content": "Nice to meet you, Alice!"},
])
print(result)
# {"success": True, "message": "Extracted 2 memories from 2 messages", ...}

m.close()

Using CognisMessage objects

Use CognisMessage instead of plain dictionaries for type safety.

from lyzr import Cognis, CognisMessage

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

result = cog.add(
    messages=[
        CognisMessage(role="user", content="I prefer dark mode in all apps."),
        CognisMessage(role="assistant", content="Noted, I'll keep that preference in mind."),
    ],
    owner_id="user_alice",
)

Multi-turn conversations

Pass longer conversations as a flat list of message pairs.

result = cog.add(
    messages=[
        {"role": "user", "content": "I'm working on a Python project."},
        {"role": "assistant", "content": "What kind of project?"},
        {"role": "user", "content": "A REST API using FastAPI."},
        {"role": "assistant", "content": "FastAPI is a great choice."},
        {"role": "user", "content": "I need help with authentication."},
        {"role": "assistant", "content": "I'd recommend OAuth2 with JWT tokens."},
    ],
    owner_id="user_alice",
    session_id="project_session",
)

Scoping with multiple identifiers

# User and agent scoped
cog.add(messages=messages, owner_id="user_alice", agent_id="support_bot")

# All three identifiers (narrowest scope)
cog.add(messages=messages, owner_id="user_alice", agent_id="support_bot", session_id="sess_001")

Async usage

import asyncio
from lyzr import Cognis

async def main():
    async with Cognis(api_key="sk-your-api-key") as cog:
        result = await cog.aadd(
            messages=[
                {"role": "user", "content": "I love hiking on weekends."},
                {"role": "assistant", "content": "That sounds fun!"},
            ],
            owner_id="user_alice",
        )

asyncio.run(main())

Send messages in natural user/assistant pairs for best extraction results. Richer, multi-turn conversations produce more useful memory records.