Memory stores
In shortReference for BaseStore, PgVectorStore, QdrantStore, embedding classes, MemoryConfig, the agent memory system prompt and store factories.
- 22 min read
- 13 sections
- Updated
- v1.0.0
- Markdown
A memory store keeps facts, preferences and past interactions across conversation threads, so an agent can recall them later. This page documents the tenxgraph.storage.store API: embeddings, PgVectorStore, QdrantStore, memory configuration, retrieval helpers and factories. A checkpointer, by contrast, saves state within one thread.
For the concepts and a walkthrough, see Long-term memory and Use a memory store.
Import paths
from tenxgraph.storage.store import (
BaseStore, PgVectorStore, QdrantStore,
MemoryConfig, AgentMemoryConfig, UserMemoryConfig,
get_agent_memory_system_prompt,
)
from tenxgraph.storage.store.store_schema import (
MemoryType, RetrievalStrategy, DistanceMetric,
MemorySearchResult, MemoryRecord,
) # MemoryType, DistanceMetric and MemorySearchResult are also exported from tenxgraph.storage.store
from tenxgraph.storage.store.embedding import (
BaseEmbedding, OpenAIEmbedding, GoogleEmbedding,
)
from tenxgraph.storage.store.long_term_memory import ReadMode # also exported from tenxgraph.storage.storeInstall the dependencies for the backends you use:
pip install openai # OpenAIEmbedding
pip install google-genai # GoogleEmbedding
pip install "10xgraph[pgvector]" # PgVectorStore (asyncpg, pgvector; Postgres 14+, pgvector extension 0.7.0+)
pip install "10xgraph[qdrant]" # QdrantStore (qdrant-client >= 1.10)Enums
MemoryType
| Value | Use case |
|---|---|
EPISODIC |
Conversation memories: what happened in a past chat. |
SEMANTIC |
Facts and general knowledge, such as “the user prefers dark mode”. |
PROCEDURAL |
How-to knowledge, such as “to reset the password, go to Settings > Security”. |
ENTITY |
Named entities and their attributes. |
RELATIONSHIP |
Connections between entities. |
DECLARATIVE |
Explicit facts and events stated by the user. |
CUSTOM |
Application-defined memory categories. |
RetrievalStrategy
| Value | Description |
|---|---|
SIMILARITY |
Vector similarity search. The default of PgVectorStore and QdrantStore when nothing else is set. |
TEXT |
Keyword / full-text search. Supported by PgVectorStore only; QdrantStore raises ValueError. |
TEMPORAL |
Time-ordered retrieval, most recent first. |
RELEVANCE |
Relevance scoring combining recency and similarity. |
HYBRID |
Vector similarity and full-text rank fused with Reciprocal Rank Fusion in PgVectorStore; QdrantStore raises ValueError. |
GRAPH_TRAVERSAL |
Navigates a knowledge graph to find connected memories. |
DistanceMetric
| Value | Description |
|---|---|
COSINE |
Cosine similarity. Best for normalised embeddings. |
EUCLIDEAN |
Euclidean (L2) distance. Sensitive to vector magnitude. |
DOT_PRODUCT |
Inner product. Fast; requires normalisation to equal cosine. |
MANHATTAN |
L1 distance. Robust to outliers. |
ReadMode
ReadMode is a string enum that controls how an agent reads long-term memory. Strings such as "preload" are accepted wherever a ReadMode is expected.
| Value | Description |
|---|---|
NO_RETRIEVAL |
Value "no_retrieval". The model cannot read past memories and no memory tools are registered. |
PRELOAD |
Value "preload". Relevant memories are searched once per graph invocation and added to the latest user message, for that request only. Every model call in the run reuses the same block. See Why memories are not system text. |
POSTLOAD |
Value "postload". The model decides when to search by calling user_memory_tool or agent_memory_tool. |
Embeddings
QdrantStore requires an embedding service to turn text into vectors for similarity search. Use a built-in class or subclass BaseEmbedding. Provider errors surface as RuntimeError.
BaseEmbedding
Abstract base class for all embedding implementations. Subclasses must implement aembed_batch, aembed and the dimension property. The example below is a toy deterministic embedding that runs without any API key, useful for tests only.
import hashlib
from tenxgraph.storage.store.embedding import BaseEmbedding
class HashEmbedding(BaseEmbedding):
"""Toy embedding for tests: hashes text into a fixed-size vector."""
async def aembed(self, text: str) -> list[float]:
digest = hashlib.sha256(text.encode()).digest()
return [b / 255 for b in digest] # 32 floats
async def aembed_batch(self, texts: list[str]) -> list[list[float]]:
return [await self.aembed(t) for t in texts]
@property
def dimension(self) -> int:
return 32
print(HashEmbedding().embed("hello")[:3]) # sync wrapper| Member | Abstract | Description |
|---|---|---|
aembed_batch(texts) |
Yes | Async: embed a list of texts. Returns one vector per text. |
aembed(text) |
Yes | Async: embed one text. Returns a vector. |
dimension |
Yes (property) | Embedding size as an integer. The collection is created with this size. |
embed_batch(texts) |
No | Sync wrapper around aembed_batch. |
embed(text) |
No | Sync wrapper around aembed. |
OpenAIEmbedding
Embedding service using OpenAI embedding models.
Requires: pip install openai
from tenxgraph.storage.store.embedding import OpenAIEmbedding
# Uses text-embedding-3-small by default; reads OPENAI_API_KEY
embedding = OpenAIEmbedding()
# Or pass the model and key explicitly
embedding = OpenAIEmbedding(
model="text-embedding-3-large",
api_key="<your-openai-key>",
)| Parameter | Type | Default | Description |
|---|---|---|---|
model |
str |
"text-embedding-3-small" |
OpenAI embedding model to use. |
api_key |
str | None |
None | OpenAI API key. If not provided, reads from OPENAI_API_KEY env var. |
Raises: ImportError if openai is not installed. ValueError if no key is found. The dimension property raises ValueError for a model name it does not know (known: text-embedding-3-small, text-embedding-3-large, text-embedding-3-xl, text-embedding-4-base, text-embedding-4-large), so wrap an unknown model in a custom BaseEmbedding subclass.
GoogleEmbedding
Embedding service using Google Gemini embedding models.
Requires: pip install google-genai
from tenxgraph.storage.store.embedding import GoogleEmbedding
# Uses gemini-embedding-001 by default; reads GOOGLE_API_KEY or GEMINI_API_KEY
embedding = GoogleEmbedding()
# Or pass the model, key and a reduced output size explicitly
embedding = GoogleEmbedding(
model="gemini-embedding-001",
api_key="<your-google-key>",
output_dimensionality=768, # optional
)| Parameter | Type | Default | Description |
|---|---|---|---|
model |
str |
"gemini-embedding-001" |
Google embedding model to use. |
api_key |
str | None |
None | Google API key. Reads from GOOGLE_API_KEY or GEMINI_API_KEY env vars if not provided. |
output_dimensionality |
int | None |
None | Optional: reduce output dimension. Some models support this. |
document_task_type |
str | None |
"RETRIEVAL_DOCUMENT" |
Gemini task type sent when embedding text to store. None sends none. |
query_task_type |
str | None |
"RETRIEVAL_QUERY" |
Gemini task type sent when embedding a search query (aembed_query). None sends none. |
BaseEmbedding.aembed_query embeds a search query and defaults to aembed for providers without a query task type; QdrantStore.asearch uses it. Vectors stored before task types were sent stay searchable.
Raises: ImportError if google-genai is not installed. ValueError if no key is found. dimension returns output_dimensionality when set, 3072 for gemini-embedding-001, and 768 for other models.
Memory configuration
MemoryConfig is the object you pass to Agent(..., memory=...). It sets the store, the retrieval mode and two optional scopes: user memory (the model can search and write) and agent memory (the model can only search). All three are pydantic models.
MemoryConfig
Primary configuration object for Agent(..., memory=...). A str retrieval mode is converted to ReadMode. limit must be at least 1 and score_threshold must not be negative, otherwise validation raises.
| Field | Type | Default | Description |
|---|---|---|---|
store |
BaseStore | None |
None | The memory store (PgVectorStore, QdrantStore, etc.). Required if memory is enabled. |
retrieval_mode |
ReadMode | str |
ReadMode.POSTLOAD |
How memories are retrieved: NO_RETRIEVAL, PRELOAD, or POSTLOAD. |
limit |
int |
5 | Maximum number of memories to retrieve per search. |
score_threshold |
float |
0.0 | Minimum similarity score for a memory to be returned. 0.0 = no threshold. |
retrieval_strategy |
RetrievalStrategy | str | None |
None | Search strategy for every scope. None uses the store’s own setting. A scope’s own retrieval_strategy wins over this one, and an explicit asearch argument wins over both. |
max_tokens |
int | None |
None | Optional token budget for retrieved memory context. |
inject_system_prompt |
bool |
True | Whether to include memory system instructions in the model’s system prompt. |
config |
dict[str, Any] |
{} | Application-defined config passed to store methods. |
user_memory |
UserMemoryConfig | None |
UserMemoryConfig() | Config for user-scoped memory (searchable and writable by model). |
agent_memory |
AgentMemoryConfig | None |
AgentMemoryConfig() | Config for agent/app-scoped memory (searchable but not writable by model). |
from tenxgraph.core import Agent
from tenxgraph.storage.store import MemoryConfig, OpenAIEmbedding, QdrantStore, ReadMode
store = QdrantStore(embedding=OpenAIEmbedding(), path="./qdrant_data")
memory = MemoryConfig(
store=store,
retrieval_mode=ReadMode.PRELOAD, # search once per invocation, inject into the user message
limit=5,
score_threshold=0.5,
max_tokens=2000,
)
agent = Agent(model="gpt-4o", memory=memory)UserMemoryConfig
Configuration for user-scoped long-term memory. The model can both search and write to user memories. memory_type and category must not be empty, and limit must be at least 1 when set.
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool |
True | Whether user memory is enabled. |
store |
BaseStore | None |
None | The store instance (if different from the parent MemoryConfig). |
memory_type |
str |
"episodic" |
Default memory type when storing. One of the MemoryType enum values. |
category |
str |
"general" |
Default memory category when storing. |
limit |
int | None |
None | Max memories to retrieve. If None, uses the parent config limit. |
score_threshold |
float | None |
None | Min similarity score, must not be negative. If None, uses the parent config threshold. |
retrieval_strategy |
RetrievalStrategy | str | None |
None | Search strategy for this scope. If None, uses the parent config’s, then the store’s. |
config |
dict[str, Any] |
{} | Optional config dict passed to store calls. |
collection |
str | Callable[[dict], str] | None |
None | Collection for this scope: a name, or a function of the run config. Always wins over any other collection. See Collections. |
user_id |
str | None |
None | Memory owner for runs without an identity; it replaces config["user_id"]. With an identity in config["user"] the identity’s user_id wins and this value is ignored. Blank strings are rejected. |
AgentMemoryConfig
Configuration for agent/app-scoped long-term memory. The model can search but not write to agent memories.
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
bool |
False | Whether agent memory is enabled (disabled by default). |
store |
BaseStore | None |
None | The store instance (if different from the parent MemoryConfig). |
memory_type |
str |
"episodic" |
Default memory type. |
category |
str |
"general" |
Default memory category. |
limit |
int | None |
None | Max memories to retrieve. |
score_threshold |
float | None |
None | Min similarity score. |
retrieval_strategy |
RetrievalStrategy | str | None |
None | Search strategy for this scope. If None, uses the parent config’s, then the store’s. |
collection |
str | Callable[[dict], str] | None |
None | Collection for this scope: a name, or a function of the run config. Always wins. See Collections. |
config |
dict[str, Any] |
{} | Optional config dict. |
agent_id |
str | None |
None | Agent identifier for scoping. |
app_id |
str | None |
None | App identifier for scoping. |
Agent memory is shared data. agent_memory_tool and the preload block always search it as the reserved owner system_user_id(agent_id) (or system_user_id(app_id) when agent_id is not set), whatever user is running, so every user of an agent sees the same agent memory. Each agent has its own owner, so two agents never see each other’s shared memory, even in one Qdrant collection. Enabling AgentMemoryConfig with neither agent_id nor app_id raises ValueError when the Agent sets up its memory:
ValueError: MemoryConfig.agent_memory is enabled but has neither agent_id nor app_id; set one so shared agent memory has its own ownerTo write shared agent memory from your own code, store under the same owner. The tool searches with user_id set to the owner, plus agent_id and thread_id (both set to your agent_id) and app_id when set, so write with the same keys:
from tenxgraph.storage import system_user_id
await store.astore(
config={
"user_id": system_user_id("customer-support-v2"),
"agent_id": "customer-support-v2",
"thread_id": "customer-support-v2",
},
content="Error E42 means the license expired.",
category="workarounds",
)With only an app_id, use {"user_id": system_user_id(app_id), "app_id": app_id}. QdrantStore filters search by user_id, memory_type and category and ignores agent_id, app_id and thread_id; the per-agent owner is what keeps agents apart.
Collections
UserMemoryConfig and AgentMemoryConfig share the collection field. A string is stripped and must not be empty (a blank name raises ValueError at validation). A function receives the run config and must return a non-empty string.
resolve_collection(run_config) -> str | None returns the scope’s collection: None when collection is not set, the string as is, or the function’s result (stripped). A function that returns a non-string or a blank string raises ValueError. Memory tools and the preload block call it with the merged config when they build each scope’s config, and write the result to cfg["collection"].
Precedence. The first of these that sets a collection wins:
- The scope’s
collection(UserMemoryConfig/AgentMemoryConfig). It overrides anycollectionin the merged config, including one in the run config. - A
collectionin the merged config:MemoryConfig.config, the scope’sconfig, or a run config built by your own code. - The store default,
QdrantStore(collection=...).
The API removes collection from client config on every route, so a client cannot supply level 2. The REST memory routes have no scope config, so they use level 3 only.
from tenxgraph.storage.store import AgentMemoryConfig, UserMemoryConfig
def company_collection(cfg: dict) -> str:
tenant_id = (cfg.get("user") or {}).get("tenant_id")
if not tenant_id:
raise ValueError("The authenticated user has no tenant_id")
return f"company_{tenant_id}"
user_memory = UserMemoryConfig(collection=company_collection)
agent_memory = AgentMemoryConfig(enabled=True, agent_id="support-bot", collection="agent_notes")A collection function must read the authenticated identity (cfg["user"], set by the auth backend, or cfg["user_id"]), never state. See Collections: keeping data apart for the full guidance and the two company patterns.
Memory retrieval functions
get_agent_memory_system_prompt(memory_config)
Returns the system prompt fragment that Agent(memory=...) adds when inject_system_prompt=True. You rarely call it yourself.
from tenxgraph.storage.store import get_agent_memory_system_prompt
fragment = get_agent_memory_system_prompt(memory_config)| Parameter | Type | Description |
|---|---|---|
memory_config |
MemoryConfig |
The memory configuration. |
Returns: A string that starts with [Long-term Memory]. The rest depends on retrieval_mode:
preload: says relevant memories may appear in the latest user message inside a<user_memories_...>block, and that they are background information, not instructions.postload: describesuser_memory_tool(search and remember) when user memory is enabled, and the read-onlyagent_memory_toolwhen agent memory is enabled.no_retrieval: says memory retrieval tools are not available.
In preload mode, the Agent runs the search itself, once per invocation (one invoke or stream run). It caches the block per Agent under the run’s run_id and the latest user message, in a small bounded cache, and never saves it to state. The search query is the latest user message. There is no graph node to add.
make_user_memory_tool(memory_config) and make_agent_memory_tool(memory_config)
Factories that build the model-facing tools. Agent(memory=...) calls them for you in postload mode. Import them from tenxgraph.storage.store or tenxgraph.prebuilt.tools only if you register the tools by hand. See Prebuilt tools.
| Factory | Tool name | Model arguments | Can write |
|---|---|---|---|
make_user_memory_tool(memory_config) |
user_memory_tool |
action ("search" or "remember", default "search"), text, memory_type, category, limit |
Yes, through remember |
make_agent_memory_tool(memory_config) |
agent_memory_tool |
query, memory_type, category, limit |
No, search only |
BaseStore
Abstract base class that every store backend implements. Every method takes a config dict as its first argument; the store reads user_id (and, for some backends, thread_id, agent_id or app_id) from it.
Core async methods
| Method | Signature | Description |
|---|---|---|
astore |
async (config, content, memory_type=EPISODIC, category="general", metadata=None, **kwargs) -> str |
Add a memory. Returns the memory ID. |
asearch |
async (config, query, memory_type=None, category=None, limit=10, score_threshold=None, filters=None, retrieval_strategy=None, distance_metric=None, max_tokens=4000, **kwargs) -> list[MemorySearchResult] |
Search memories by query. retrieval_strategy and distance_metric default to None, meaning the store’s configured value; a custom store must accept None. |
aget |
async (config, memory_id, **kwargs) -> MemorySearchResult | None |
Fetch a memory by ID. |
aget_all |
async (config, limit=100, **kwargs) -> list[MemorySearchResult] |
List memories in the config’s scope. |
aupdate |
async (config, memory_id, content, metadata=None, **kwargs) -> Any |
Update a memory’s content. |
adelete |
async (config, memory_id, **kwargs) -> Any |
Delete a memory by ID. |
aforget_memory |
async (config, **kwargs) -> Any |
Delete memories for the user_id in config. thread_id is an optional extra filter. QdrantStore and PgVectorStore also narrow by the keyword arguments memory_type, category and filters (combined with AND). On QdrantStore a filters value that is not a string, integer or boolean raises ValueError; on PgVectorStore see filters. |
asetup |
async () -> Any |
Create the collection or other backing resources. Implemented by QdrantStore and PgVectorStore; the base class raises NotImplementedError. |
aping |
async () -> None |
Abstract. Return when the store’s backend is reachable, raise when it is not. Must be read-only and cheap, because a server may call it on every readiness probe. An in-process store just returns. 10xgraph-api calls it for /health/ready and at startup. A custom store that does not implement it raises TypeError when created. |
arelease |
async () -> None |
Release connections. Not abstract, but the base implementation raises NotImplementedError; PgVectorStore overrides it. |
There is no bulk abatch_store; call astore in a loop or with asyncio.gather.
QdrantStore.aping() lists the collections on the server, PgVectorStore.aping() runs SELECT 1, and InMemoryStore.aping() returns at once.
Sync wrappers
store.store(config, content)
store.search(config, query)Each async method has a sync wrapper named without the a prefix (store, search, get, get_all, update, delete, forget_memory, setup, release). Use the async variants in async code.
Config dictionary
config = {
"user_id": "alice", # required by every store operation
"thread_id": "thread-1", # optional; QdrantStore reads it
}The user_id rule and system_user_id
Every long-term memory operation needs a non-empty user_id, taken from the config dict. A missing, None, empty or blank value raises:
ValueError: user_id is required for memory operations; use system_user_id(name) for shared dataThis applies to astore, asearch, aget, aget_all, aupdate, adelete and aforget_memory on QdrantStore and PgVectorStore. A store never falls back to searching or deleting across all users.
Two rules refine this:
- Wide reads. When the caller’s identity has reach
all(see Multi-tenant data), reads and updates (asearch,aget,aget_all,aupdate,adelete) skip the user filter and see every user’s memories. Writes (astore) andaforget_memorystill need a concreteuser_idunder this reach. aforget_memoryalways filters byuser_id.thread_idis an optional extra filter, never a replacement. A narrowing argument is never dropped silently: it is applied or the call raises, so a narrow forget cannot delete everything.
Data that belongs to no person, such as agent/app memory and RAG knowledge bases, is owned by a reserved system id. Three names are exported from tenxgraph.storage.store and tenxgraph.storage:
| Name | Description |
|---|---|
SYSTEM_USER_PREFIX |
The constant "__system__". Every system owner starts with it. |
system_user_id(name) |
Returns "__system__:<name>". Raises ValueError when name is empty. Each name is its own owner, so shared data sets stay separate. |
is_system_user_id(user_id) |
Returns True for any str that starts with __system__. |
from tenxgraph.storage import system_user_id, is_system_user_id
# also available as: from tenxgraph.storage.store import system_user_id
owner = system_user_id("knowledge_base") # "__system__:knowledge_base"
await store.astore(config={"user_id": owner}, content="Refunds take 5 days.")
is_system_user_id(owner) # TrueAgent and app memory use system_user_id(agent_id) (or system_user_id(app_id)); RAGAgent searches system_user_id("knowledge_base") by default. The 10xGraph API refuses any authenticated identity whose user_id starts with __system__ (HTTP 401 “This user id is reserved”, WebSocket close code 1008), so no caller can act as a shared owner. Records written earlier with an empty owner are not found by any user-scoped read; re-index them under the intended owner.
MemorySearchResult
Returned by asearch, aget and aget_all. Each result represents a matching memory.
| Field | Type | Description |
|---|---|---|
id |
str |
Memory ID. |
content |
str |
The memory text. |
score |
float |
Similarity or relevance score, at least 0.0. |
memory_type |
MemoryType |
Categorisation. |
metadata |
dict |
Application-defined metadata. |
vector |
list[float] | None |
Embedding vector (if returned by backend). |
user_id |
str | None |
User scope. |
thread_id |
str | None |
Thread where this memory was created. |
timestamp |
datetime | None |
Creation time. |
QdrantStore
Vector store backed by Qdrant. Production-ready for similarity search.
import asyncio
from tenxgraph.storage.store import OpenAIEmbedding, QdrantStore
# Local Qdrant (persisted to disk)
store = QdrantStore(
embedding=OpenAIEmbedding(),
path="./qdrant_data",
)
# Remote Qdrant
store = QdrantStore(
embedding=OpenAIEmbedding(),
host="localhost",
port=6333,
)
# Qdrant Cloud
store = QdrantStore(
embedding=OpenAIEmbedding(),
url="https://xyz.qdrant.io",
api_key="<your-qdrant-api-key>",
)
asyncio.run(store.asetup()) # creates the collection; pass the store to graph.compile(store=store)path, url and host/port are checked in that order: path wins, then url, otherwise host (default localhost) and port (default 6333). Extra keyword arguments go to AsyncQdrantClient.
Constructor parameters
| Parameter | Type | Description |
|---|---|---|
embedding |
BaseEmbedding |
Embedding service used to vectorise text before storage and search. |
path |
str | None |
Local path for embedded Qdrant server. |
host |
str | None |
Remote Qdrant host. |
port |
int | None |
Remote Qdrant port (default: 6333). |
url |
str | None |
Qdrant Cloud URL. |
api_key |
str | None |
Qdrant Cloud API key. |
collection |
str | Callable[[dict], str] | None |
Default collection: a name, or a function (config) -> name called with the config of each operation. Used when the config has no collection. Defaults to DEFAULT_COLLECTION, which is "agentflow_memories". A function must return a non-empty string (otherwise ValueError) and must read identity from config["user"] or config["user_id"], never state. |
distance_metric |
DistanceMetric |
Distance metric for the collection. Default: COSINE. |
**kwargs |
Any |
Passed to AsyncQdrantClient. |
asetup() and the default collection. With a name as the default, asetup() creates that collection. With a function, asetup() creates nothing, because there is no fixed name; each collection is created, with its payload indexes, by the first write or search that uses it. A collection named by config["collection"] is created the same way.
PgVectorStore
Long-term memory and RAG in Postgres with the pgvector extension, in one table next to the PgCheckpointer tables. For a walkthrough see How to use PgVectorStore; for tenant and extra columns see Multi-tenant data.
Requires PostgreSQL 14 or newer, the pgvector extension 0.7.0 or newer, and pip install "10xgraph[pgvector]". A text-only store (embedding=None) does not need the extension.
from tenxgraph.storage.store import OpenAIEmbedding, PgVectorStore
store = PgVectorStore(
embedding=OpenAIEmbedding(),
dsn="postgresql://user:pass@localhost:5432/app",
)
await store.asetup()Constructor parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
embedding |
BaseEmbedding | None |
required | Embedding service, or None for a text-only store (no embedding column). |
dsn |
str | None |
None |
Connection string. The store creates a pool and closes it in arelease(). |
pool |
asyncpg Pool | None |
None |
Existing pool. Never closed by the store. Pass dsn or pool, not both. |
pool_config |
dict | None |
None |
Extra asyncpg.create_pool arguments for a pool built from dsn. |
schema |
str |
"public" |
Postgres schema of the table. |
table |
str |
"tenxgraph_memories" |
Table name, at most 48 characters. |
collection |
str | Callable[[dict], str] | None |
None |
Default collection: a name or a function of the config. |
distance_metric |
DistanceMetric | str |
COSINE |
Metric of the HNSW index and the default for searches. |
retrieval_strategy |
RetrievalStrategy | str | None |
None |
Default strategy: SIMILARITY, TEXT or HYBRID. None means SIMILARITY, or TEXT when embedding=None. |
hybrid_weights |
tuple[float, float] |
(1.0, 1.0) |
(vector_weight, text_weight) for HYBRID. |
rrf_k |
int |
60 |
The Reciprocal Rank Fusion constant. |
hybrid_candidates |
int | None |
None |
Rows each list contributes to fusion. None means max(4 * limit, 20). |
text_search_config |
str |
"english" |
Postgres text search configuration, fixed when the table is created. |
on_embedding_error |
"fallback" | "raise" |
"fallback" |
On an embedding failure, save text without an embedding and search as TEXT, or raise. |
acquire_timeout |
float | None |
30.0 |
Seconds to wait for a pooled connection. |
tenant_columns |
list | dict | None |
None |
Isolation columns (text, bigint, integer, uuid). Values come only from config["user"]. |
extra_columns |
list | dict | None |
None |
Your own data columns, any Postgres type. |
row_level_security |
bool |
False |
Also enforce tenant columns with native row-level security. Needs tenant_columns. |
ddl_lock_timeout |
float | None |
10.0 |
Seconds a setup DDL statement waits for a table lock; on timeout setup raises SetupLockTimeoutError. None waits forever. |
Methods specific to this store: await store.adrop_legacy_key_index() -> list[str] drops the memory_key index of an earlier declaration after tenant columns were added (see Multi-tenant data). It is deprecated and will be removed in the next breaking release (1.5 or 2.0). Column names user_id, kind, tenant, roles, permissions, reach and claims are reserved.
Methods beyond BaseStore
| Method | Description |
|---|---|
abackfill_embeddings(batch_size=100) |
Embed every memory saved without an embedding and return how many were filled. Raises on a text-only store. |
filter_schema |
Attribute. The FilterSchema for tenxgraph.storage.sql_filter.validate_filters. |
tenant_column_names |
Attribute. The declared tenant column names. |
asearch, aget_all and aforget_memory take filters; see Filters for operators and limits. Keys that are not columns match top-level metadata keys exactly.
Store factory functions
Convenience functions to create and configure store instances with common patterns.
create_local_qdrant_store(path, embedding, collection=...)
Create a QdrantStore with a local embedded Qdrant server.
from tenxgraph.storage.store import create_local_qdrant_store, OpenAIEmbedding
store = create_local_qdrant_store(
embedding=OpenAIEmbedding(),
path="./qdrant_data",
)| Parameter | Type | Description |
|---|---|---|
embedding |
BaseEmbedding |
The embedding service. |
path |
str |
Local directory path for Qdrant persistence. |
collection |
str | Callable[[dict], str] |
Default collection: a name or a function of the config. Default "agentflow_memories". |
**kwargs |
Any |
Passed to QdrantStore. |
Returns: A configured QdrantStore instance.
create_remote_qdrant_store(host, port, embedding, collection=...)
Create a QdrantStore connected to a remote Qdrant server.
from tenxgraph.storage.store import create_remote_qdrant_store, OpenAIEmbedding
store = create_remote_qdrant_store(
embedding=OpenAIEmbedding(),
host="localhost",
port=6333,
)| Parameter | Type | Description |
|---|---|---|
embedding |
BaseEmbedding |
The embedding service. |
host |
str |
Remote host address. |
port |
int |
Remote server port. Required (typically 6333). |
collection |
str | Callable[[dict], str] |
Default collection: a name or a function of the config. Default "agentflow_memories". |
**kwargs |
Any |
Passed to QdrantStore. |
Returns: A configured QdrantStore instance.
create_cloud_qdrant_store(url, api_key, embedding, collection=...)
Create a QdrantStore connected to Qdrant Cloud.
from tenxgraph.storage.store import create_cloud_qdrant_store, OpenAIEmbedding
store = create_cloud_qdrant_store(
embedding=OpenAIEmbedding(),
url="https://xyz.qdrant.io",
api_key="<your-qdrant-api-key>",
)| Parameter | Type | Description |
|---|---|---|
embedding |
BaseEmbedding |
The embedding service. |
url |
str |
Qdrant Cloud cluster URL. |
api_key |
str |
Qdrant Cloud API key. |
collection |
str | Callable[[dict], str] |
Default collection: a name or a function of the config. Default "agentflow_memories". |
**kwargs |
Any |
Passed to QdrantStore. |
Returns: A configured QdrantStore instance.
Wiring into Agent memory
Pass a MemoryConfig to the Agent and the same store to graph.compile. With PRELOAD the agent searches memory itself before each call; with POSTLOAD it needs a ToolNode so the memory tools can be registered.
from tenxgraph.core import Agent, StateGraph
from tenxgraph.core.state import AgentState
from tenxgraph.storage.store import MemoryConfig, OpenAIEmbedding, QdrantStore, ReadMode
from tenxgraph.utils.constants import END
store = QdrantStore(embedding=OpenAIEmbedding(), path="./qdrant_data")
agent = Agent(
model="gpt-4o",
memory=MemoryConfig(store=store, retrieval_mode=ReadMode.PRELOAD, limit=5),
)
graph = StateGraph(AgentState)
graph.add_node("MAIN", agent)
graph.set_entry_point("MAIN")
graph.add_edge("MAIN", END)
app = graph.compile(store=store) # the store is injected into memory tools and nodesMemory is scoped by the user_id you pass in the invoke config. See Use a memory store for a full run.
Direct store usage in nodes
A node can call the store directly through dependency injection, for example to write custom memory logic.
from injectq import Inject
from tenxgraph.core.state import AgentState
from tenxgraph.storage.store import BaseStore
from tenxgraph.storage.store.store_schema import MemoryType, RetrievalStrategy
async def remember_node(
state: AgentState,
config: dict,
store: BaseStore = Inject[BaseStore],
) -> list:
text = state.context[-1].text()
# Retrieve relevant memories
memories = await store.asearch(
config={"user_id": config.get("user_id")},
query=text,
memory_type=MemoryType.EPISODIC,
retrieval_strategy=RetrievalStrategy.SIMILARITY,
limit=5,
)
context = "\n".join(m.content for m in memories) # use this in a prompt or state
# Store the user's latest message as a memory
await store.astore(
config={"user_id": config.get("user_id")},
content=text,
memory_type=MemoryType.EPISODIC,
)
return [] # no new messages; state enriched by memories aboveThe store parameter is injected when you pass store= to graph.compile().
Common errors
| Error | Cause | Fix |
|---|---|---|
ImportError: qdrant-client package is required for QdrantStore |
qdrant-client is not installed. |
pip install "10xgraph[qdrant]". |
ImportError: asyncpg is required for PgVectorStore |
The pgvector extra is not installed. |
pip install "10xgraph[pgvector]". |
RuntimeError naming the pgvector extension |
asetup() could not create the vector extension, or it is older than 0.7.0. |
Have an admin run CREATE EXTENSION vector; (or ALTER EXTENSION vector UPDATE;), or use embedding=None. |
ValueError: OpenAI API key must be provided... |
No api_key and no OPENAI_API_KEY. |
Set the variable or pass api_key. |
ValueError: user_id is required for memory operations; use system_user_id(name) for shared data |
A store call has a missing, None, empty or blank user_id. |
Put the user’s id in the config dict, or system_user_id(name) for shared data. See The user_id rule. |
RuntimeError: Memory requires an existing ToolNode... |
Agent(memory=...) in POSTLOAD mode without a tool node. |
Pass tool_node= or use PRELOAD. |
NotImplementedError from asetup |
Called asetup() on a store that does not implement it. |
QdrantStore and PgVectorStore implement it. |