Skip to main content
Cognis organizes memory using three scope identifiers: owner_id, agent_id, and session_id. You provide at least one of these when adding or searching memories. The combination determines which memories are stored together and retrieved together.

​
Session memory

Session memory is scoped to a single conversation by providing a session_id. Facts added within a session are retrievable by that session identifier. Use session memory when you want the agent to maintain context across turns in one conversation but not carry it into future sessions. 
cog.add(
    messages=messages,
    owner_id="user_alice",
    session_id="sess_support_001",
)

results = cog.search(
    query="billing issue",
    owner_id="user_alice",
    session_id="sess_support_001",
)

​
Long-term memory

Long-term memory is scoped to a user or agent rather than a specific session. Facts added with only an owner_id are retrievable in any future session for that user, making them available whenever the user returns. 
# Store a durable preference
cog.add(
    messages=[
        {"role": "user", "content": "I always prefer metric units."},
        {"role": "assistant", "content": "Noted, I'll use metric going forward."},
    ],
    owner_id="user_alice",
)

# Retrieve in any future session
results = cog.search(query="unit preferences", owner_id="user_alice")

​
Cross-session memory

Cross-session memory spans multiple sessions for the same user. By searching with only owner_id, Cognis returns relevant facts regardless of which session they were created in. This is useful for agents that handle repeat users and need continuity without knowing the specific session a fact came from. 
# All sessions for user_alice are searched
results = cog.search(query="previous support topics", owner_id="user_alice")

​
Agent-scoped memory

You can isolate memories per agent by including agent_id. This prevents facts from a support agent leaking into a sales agent’s context for the same user. 
# Scoped to a specific agent
cog.add(
    messages=messages,
    owner_id="user_alice",
    agent_id="support_bot",
)

results = cog.search(
    query="open tickets",
    owner_id="user_alice",
    agent_id="support_bot",
)

​
Scope combinations

owner_idagent_idsession_idScope
YesNoNoAll sessions for a user across all agents
YesYesNoAll sessions for a user on a specific agent
YesNoYesA single session for a user
YesYesYesA single session for a user on a specific agent
At least one identifier is required. Providing all three gives the narrowest scope and is recommended for production agents with multiple users and multiple agent types.

​
Next steps