Store

The Store API gives your agents persistent storage for key-value data with optional semantic search. Use it for conversation memory, user preferences, knowledge retrieval, or any data that needs to persist across runs.

Key-value operations

The store works without any configuration — it’s available by default.

Put an item

import asyncio
from langgraph_sdk import get_client


async def main():
    client = get_client(url="http://localhost:2026")

    await client.store.put_item(
        namespace=["users", "alice", "preferences"],
        key="theme",
        value={"color": "dark", "font_size": 14},
    )


asyncio.run(main())

Values must be JSON objects (dicts). Primitive values like strings or numbers are not accepted. The snippets below assume you are inside an async def function with an initialized client — see the example above.

Get an item

item = await client.store.get_item(
    namespace=["users", "alice", "preferences"],
    key="theme",
)
print(item["value"])  # {"color": "dark", "font_size": 14}

Delete an item

await client.store.delete_item(
    namespace=["users", "alice", "preferences"],
    key="theme",
)

Search items

results = await client.store.search_items(
    namespace_prefix=["users", "alice"],
    limit=10,
)

for item in results["items"]:
    print(f"{item['namespace']}/{item['key']}: {item['value']}")

Namespaces

Namespaces organize your data hierarchically. They work like directory paths:

["users", "alice", "preferences"]     → User preferences
["users", "alice", "conversations"]   → Conversation history

List namespaces

namespaces = await client.store.list_namespaces(
    prefix=["users"],
)
# Returns: [["users", "alice", "preferences"], ["users", "alice", "conversations"], ...]

Namespace scoping

All store operations are automatically scoped to the authenticated user’s namespace under ["users", <user_id>]. This means:

An empty namespace defaults to ["users", <user_id>]
A namespace already under your user prefix (e.g. ["users", "alice", "docs"]) passes through unchanged
Any other namespace (e.g. ["configs"]) is automatically prefixed to ["users", <user_id>, "configs"]

This ensures users can never access each other’s data, even if they craft a request with another user’s namespace.

Configurable scoping

Beyond the default per-user scope, you can define configurable scopes: a map of namespace prefix → list of User attributes under store.scopes in aegra.json. A namespace starting with a configured prefix is isolated under [prefix, *<user attribute values>], where the values come from the authenticated user populated by your auth handler. Every user whose attribute values match lands in the same scope, so data is shared exactly as widely as those attributes. Mapping an attribute many users share (like org_id) is the common way to share a pool across a group — for example, a knowledge base or agent skills that every member can read and contribute to. For example, to share data across an organization, map "orgs" to a list containing the user’s org_id in aegra.json:

{
  "store": {
    "scopes": {
      "orgs": ["org_id"]
    }
  }
}

# Shared across all members of the caller's organization
await client.store.put_item(
    namespace=["orgs", "<org_id>", "shared-skills"],
    key="summarize-ticket",
    value={
        "name": "summarize-ticket",
        "description": "Condenses a support ticket thread.",
        "instructions": "..."
    },
)

A configured scope follows the same rule as user scoping (using the "orgs" → org_id example):

A fully-qualified namespace ["orgs", <org_id>, ...] passes through unchanged. The <org_id> is visible in get/search/list_namespaces responses, which echo the scoped namespace.
Any namespace not fully qualified with your own org_id (including a foreign org id) is buried under ["orgs", <org_id>, ...], so members can never reach another organization’s data.
A request using the "orgs" prefix when the user has no org_id returns 403 Forbidden.

An empty or unconfigured prefix always defaults to user scope — a configured scope is never applied implicitly.

Partitioning by multiple attributes

A scope can list more than one attribute. The namespace is then partitioned by every listed attribute, in order. Reach for this when no single attribute is enough on its own — for example, isolating data per organization and per region, where each org/region pair is its own partition:

{
  "store": {
    "scopes": {
      "regional": ["org_id", "region"]
    }
  }
}

A namespace ["regional", ...] is isolated under ["regional", <org_id>, <region>, ...]. All listed attributes are required — a user missing any of them gets 403 Forbidden, exactly as with a single-attribute scope. You can map any prefix to any attributes your auth handler sets (team_id, tenant_id, region, …), and configure several scopes at once. The "users" prefix is reserved for per-user isolation and cannot be remapped.

Semantic search

When you configure vector embeddings, the store gains semantic search capabilities. Items are automatically embedded when stored and can be queried by meaning.

Configuration

Add the store section to your aegra.json:

{
  "store": {
    "index": {
      "dims": 1536,
      "embed": "openai:text-embedding-3-small",
      "fields": ["$"]
    }
  }
}

See the semantic store guide for detailed configuration options and embedding providers.

Semantic query

# Store some knowledge
await client.store.put_item(
    namespace=["knowledge"],
    key="python-tips",
    value={"text": "Use list comprehensions for concise iteration in Python"},
)

await client.store.put_item(
    namespace=["knowledge"],
    key="testing-tips",
    value={"text": "Always write tests before refactoring existing code"},
)

# Search by meaning
results = await client.store.search_items(
    namespace_prefix=["knowledge"],
    query="How should I write Python loops?",
    limit=5,
)
# Returns the python-tips item based on semantic similarity

Using the store in graphs

Your agents can access the store within graph nodes via LangGraph’s built-in store injection. Items stored via the API are available to the graph, and vice versa.

from langgraph.store.base import BaseStore


def my_node(state, *, store: BaseStore):
    """The store is automatically injected by LangGraph."""
    # Read from the store
    items = store.search(("users", state["user_id"], "preferences"))
    prefs = items[0].value if items else {}

    # Write to the store
    store.put(("users", state["user_id"], "history"), key="last_query", value={"q": state["query"]})

    return {"preferences": prefs}

Add the node to your graph as usual — LangGraph injects the store parameter automatically when the graph is compiled with a store backend (which Aegra provides).

Getting started

Core concepts

Data & storage

Configuration

Contributing

Reference

Key-value operations

Put an item

Get an item

Delete an item

Search items

Namespaces

List namespaces

Namespace scoping

Configurable scoping

Partitioning by multiple attributes

Semantic search

Configuration

Semantic query

Using the store in graphs

​Key-value operations

​Put an item

​Get an item

​Delete an item

​Search items

​Namespaces

​List namespaces

​Namespace scoping

​Configurable scoping

​Partitioning by multiple attributes

​Semantic search

​Configuration

​Semantic query

​Using the store in graphs

Key-value operations

Put an item

Get an item

Delete an item

Search items

Namespaces

List namespaces

Namespace scoping

Configurable scoping

Partitioning by multiple attributes

Semantic search

Configuration

Semantic query

Using the store in graphs