یک مخزن، آیتمهای JSON را ذیل فضاهای نامی نگه میدارد که همهی تردها میتوانند آنها را بخوانند؛ و کاربران را فقط تا همان اندازهای از یکدیگر تفکیک میکند که پیشوندِ فضای نامِ ساختهشده در کد شما اجازه میدهد.
کاربری به دستیارتان میگوید که پاسخهای کوتاه را ترجیح میدهد. یک هفته بعد، گفتوگوی جدیدی آغاز میکند که ترد (thread) تازهای است؛ و دستیار همهچیز را فراموش کرده است. چکپوینتر (checkpointer) فقط وضعیت یک ترد را نگه میدارد. واقعیتی که باید فراتر از عمر یک ترد زنده بماند، به جای دیگری نیاز دارد.
با پایان این بخش، میتوانید خاطرات را در یک مخزن ذخیره و جستجو کنید، آنها را از داخل یک ابزار بخوانید و کاربران را از طریق فضای نام (namespace) از یکدیگر تفکیک کنید.
آیتمها و فضاهای نام
مخزن (Store): شیئی که آیتمهای JSON را بر اساس فضای نام و کلید ذخیره میکند و میان همهی تردهای یک گراف به اشتراک گذاشته میشود. InMemoryStore، SqliteStore و PostgresStore نمونههایی از مخزن هستند.
فضای نام (Namespace): تاپلی از رشتهها، مانند ("users", "ada", "memories")، که آیتمهای یک مخزن را گروهبندی میکند. هر رشته یک برچسب (label) به شمار میرود.
آیتم (Item): یک مقدار در مخزن، به همراه فضای نام، کلید، و زمانهای ایجاد و بهروزرسانی آن.
صفحهی مستنداتِ حافظهی بلندمدت، حافظه را دقیقاً به همین شیوه روی مخازن پیادهسازی میکند {{docs oss/python/langchain/long-term-memory}}. کلاس InMemoryStore را از langgraph.store.memory ایمپورت کنید. در صفحهی مستنداتِ مخازن، این نام به کلاسی در langchain_core.stores ارجاع داده شده که یک مخزنِ کلید-مقدارِ متفاوت و بدون پشتیبانی از فضای نام است {{docs oss/python/langgraph/stores}}. این راهنما تداخل مذکور را با عنوان تداخل D106 ثبت میکند.
کیت، چهار آیتم را برای دو کاربر ذخیره میکند و یکی از آنها را بازمیخواند:
get:
{
"__type__": "Item",
"namespace": [
"users",
"ada",
"memories"
],
"key": "m1",
"value": {
"text": "prefers short answers"
},
"created_at": "<time>",
"updated_at": "<time>"
}متد list_namespaces() هر سه فضای نام را برمیگرداند. با ارسال آرگومان prefix=("users", "ada")، فقط دو فضای نامِ مربوط به ada فهرست میشوند. در صورت تعیین max_depth=2، هر فضای نام به دو برچسب برش میخورد و خروجی شامل ("users", "ada") و ("users", "grace") خواهد بود.
متد search بر اساس تطابق پیشوند عمل میکند
متد search(namespace_prefix) آیتمهای تمام فضاهای نامی را که با آن پیشوند آغاز میشوند برمیگرداند. مستندات مخازن هم همین را میگوید: این پیشوند، تطابق دقیق (exact match) نیست {{docs oss/python/langgraph/stores}}. جستجو برای ("users", "ada") آیتمهای هر دو بخش memories و settings را برگرداند:
search(('users', 'ada')):
[
[
[
"users",
"ada",
"memories"
],
"m1",
…
[
"users",
"ada",
"memories"
],
"m2",
…
[
"users",
"ada",
"settings"
],
"theme",مقادیر کوتاه شدهاند.
مستندات مخازن اضافه میکند که ترتیب نتایج به بکاند بستگی دارد {{docs oss/python/langgraph/stores}}. با استفاده از filter میتوان مقادیر درون همان پیشوند را مطابقت داد و متد delete یک آیتم را حذف میکند؛ بنابراین فراخوانی get پس از آن، مقدار null برمیگرداند. تصویر درختی را نشان میدهد که این فراخوانیها در طول آن پیمایش میکنند.
مخزنی که شاخص (index) داشته باشد، امکان جستجوی معنایی (semantic search) روی فیلدهای تعیینشده را فراهم میکند. کیت، سه آیتمِ مربوط به ada را با مدل nomic-embed-text روی Ollama و با بعد (dims) 768 شاخصگذاری کرد. در جستجوی عبارت works in Pune، امتیازِ آیتمِ خود این عبارت 1.0 و امتیاز likes tea برابر 0.350555 شد. پرسش ?Which city is Ada's office in نام هیچ آیتمی را در خود نداشت، اما باز هم عبارت works in Pune با امتیاز 0.484968 در رتبهی اول و likes tea با امتیاز 0.386065 در رتبهی دوم قرار گرفت.
خواندن مخزن توسط ابزار
تابع create_agent(..., store=store) مخزن را از طریق ToolRuntime به هر ابزار میفرستد. ابزار کیت، شناسه کاربر را از زمینهی اجرا (run context) میخواند و فضای نام همان کاربر را جستجو میکند:
@tool
def recall(runtime: ToolRuntime) -> str:
"""Recall what is known about the current user."""
user = runtime.context["user"]
return "; ".join(i.value["text"] for i in runtime.store.search(("users", user, "memories")))user ada: tool returned ['prefers short answers']
…
user grace: tool returned ['prefers long answers']پاسخهای مدل کوتاه شدهاند.
مدل Qwen3 4B در هر دو اجرا ابزار recall را صدا زد. به Ada پاسخ داد: I know you prefer short answers. و به Grace پاسخی طولانی دربارهی تمایلش به جوابهای مفصل داد.
شناسه کاربر از context استخراج میشود که کد شما آن را مقداردهی کرده است، نه از مدل. اگر مدل اجازه داشت نام کاربر را در آرگومان ابزار بیاورد، میتوانست آیتمهای کاربری دیگر را هم بخواند. در هر اجرا، یک هشدار PydanticSerializationUnexpectedValue برای فیلد context هم صادر شد؛ چرا که ایجنت برای این دیکشنری context_schema تعریف نکرده بود. این هشدار تأثیری روی نتیجه نگذاشت.
تفکیک فضای نام
ما میزان تفکیک را سنجیدیم: روی سیستم Mac با پردازنده Apple M1 Max دارای 10 هسته و 64 گیگابایت حافظه، با یک اجرا به ازای هر پرسوجو. مخازن مورد بررسی شامل InMemoryStore، SqliteStore و PostgresStore روی PostgreSQL 14 بودند. هشت کاربر، هر کدام یک آیتم ذیل ("users", <user>, "memories") داشتند. پنج مورد از شناسههای کاربری کاراکترهای عملگر LIKE در SQL و GLOB در SQLite بودند: a_ice، %، *، al?ce و [a]lice. برای هر کاربر و در هر مخزن، جستجو با پیشوندِ همان کاربر فقط آیتم خود او را برگرداند: 0 از 24 جستجو با دیگر کاربران تداخل پیدا کرد.
همین اجراها چهار نقطهای را نشان دادند که در آنها تفکیک دادهها به کد شما وابسته است:
- فراخوانی
list_namespaces(prefix=("users", "*"))در هر سه مخزن، فضاهای نامِ تمام کاربران را برگرداند. کاراکتر*در متدlist_namespacesنویسه عمومی (wildcard) و در متدsearchیک کاراکتر معمولی است. پیش از ساختن پیشوند با استفاده از شناسه کاربر، از نبود شناسه کاربریِ*مطمئن شوید. - فراخوانی
search(())با یک پیشوند خالی، آیتمهای تمام کاربران را برگرداند: 9 آیتم درInMemoryStoreو 8 آیتم در دو مخزن دیگر. هرگز با پیشوندی کوتاهتر از برچسب کاربر جستجو نکنید. - یک برچسب ناقص هیچ چیزی را مطابقت نداد: پیشوند
("users", "ali")بهaliceنرسید. وصلهی مربوط به گزارش امنیتی GHSA-47pj-3jcm-6whg در نسخهی ثابت این بسته پابرجاست. - برچسب دارای کاراکتر
.در متدهایputوgetبا خطایInvalidNamespaceErrorرد شد. مخازنSqliteStoreوPostgresStoreدر متدbatchنیز آن را رد کردند.InMemoryStoreبرچسب("users", "bob.x")را از طریقbatchذخیره کرد، و اجرای یکGetOpروی("users", "alice.memories")یک فضای نام خالی ساخت. هیچ آیتمی بین کاربران جابهجا نشد.
فیلتر همیشه درون پیشوند خود باقی میماند. فراخوانی search(("users", "bob"), filter={"owner": "alice"}) نتیجهای برنگرداند. جستجوی معنایی نیز محدود به پیشوند خود ماند. با مدل nomic-embed-text روی Ollama، پرسوجویی که بیشترین تطابق را با آیتم alice داشت، ذیل پیشوند bob تنها آیتمهای متعلق به bob را برگرداند.
فایلهای حافظه در Deep Agents و کارخانهی فضای نام
ایجنت عمیق (deep agent) حافظه را در قالب فایل میخواند و مینویسد. ابزار CompositeBackend مسیرهای زیرمجموعه /memories/ را به یک StoreBackend میفرستد و StoreBackend هر فایل را در قالب یک آیتم ذخیره میکند. فضای نامِ تمام آیتمها از کارخانهای (factory) میآید که شما ارسال میکنید، و ابزارهای ایجنت هرگز خودشان آن را انتخاب نمیکنند {{code libs/deepagents/deepagents/backends/store.py:98-168}}.
StoreBackend: یک بکاند Deep Agents که فایلها را داخل مخزن LangGraph، ذیل فضای نامی نگه میدارد که یک کارخانه برای هر اجرا برمیگرداند.
در نسخهی ثابت، ارسال این کارخانه اجباری است. فراخوانی StoreBackend(store=s) خطای TypeError: missing 1 required keyword-only argument: 'namespace' را بالا آورد. در صفحهی مستنداتِ بکاندها هنوز نوشته شده که بدون کارخانه، پیشفرضِ قدیمی assistant_id را میخواند؛ در نتیجه همهی کاربرانِ یک دستیار، حافظهی مشترک دارند {{docs oss/python/deepagents/backends}}. این پیشفرض در نسخهی 0.7.38 حذف شده است و این راهنما آن صفحه از مستندات را قدیمی و منسوخ میداند.
مثالهای ترکیبی در همان صفحه، آرگومان namespace=lambda _rt: ("memories",) را پاس میدهند. این یعنی یک فضای نام یکسان برای همهی کاربران ایجنت. اگر این کد را درون سرویسی با چند کاربر کپی کنید، ایجنتِ هر کاربر فایلهای بقیهی کاربران را میخواند.
ما این موضوع را روی یک ایجنت واقعی سنجیدیم. یک ایجنت عمیق مبتنی بر Qwen3 8B روی Ollama در Mac با دمای 0 اجرا شد که مسیر /memories/ آن روی یک StoreBackend قرار داشت. در هر نشست، Alice از آن خواست تا کد یک کمد را در مسیر /memories/notes.md ذخیره کند. سپس Bob، در ترگی جدید، کدهای کمدِ ذخیرهشده ذیل /memories/ را درخواست کرد. هر نشست از یک مخزن تازه استفاده میکرد و ما به ازای هر ساختار، 10 نشست روی InMemoryStore و 10 نشست روی PostgresStore (با PostgreSQL 14) اجرا کردیم. ذخیرهسازی داده توسط Alice در همهی 80 نشست بدون مشکل انجام شد.
تصویر نتایج هر نشست را نشان میدهد:
- کارخانهی مستندات،
("memories",): ایجنت Bob ابزارهایlsوread_fileرا صدا زد و کد Alice را به او تحویل داد؛ در 10 نشست از 10 نشست روی هر مخزن. - کارخانهی اختصاصی برای هر کاربر،
("users", rt.context.user_id): ایجنت Bob یک پوشهی خالی را فهرست کرد و گفت کدی وجود ندارد؛ در 10 نشست از 10 نشست روی هر مخزن. - همان کارخانه، به اضافهی یک ابزار
recallکه پیشوند("users",)را میکاود: این همان ابزار سادهلوحانهی بخش تفکیک فضای نام است که پیشوند آن یک برچسب کم دارد. مدل در پاسخ به سؤالی دربارهی مسیر/memories/فقط از دستورlsاستفاده کرد و در 20 نشست هیچ دادهای لو نرفت. اما وقتی از آن خواسته شد از ابزار بازخوانی خود استفاده کند،recallرا صدا زد و کد Alice را در 10 نشست از 10 نشست روی هر مخزن به Bob تحویل داد.
نتیجهی آزمون ابزار recall، درس اصلی این تصویر است. بکاندِ فایلی که به ازای هر کاربر تعریف شده بود کاربران را جدا نگه داشت؛ اما یک ابزار که پیشوند کوتاهتری را جستجو میکرد همهچیز را به باد داد، و مدل به محض اینکه کاربر نام آن ابزار را برد از آن استفاده کرد. اینکه یک مدل داده لو بدهد یا نه به پرامپت بستگی دارد؛ بنابراین مسیر حرکت دادهها را بسنجید، نه فقط پاسخهای خروجی را. در یک نشست دیگر، Bob از ایجنت خواست بدون بردن نام /memories/، «حافظهی بلندمدتت را بررسی کن». ایجنت هیچ ابزاری را فراخوانی نکرد و گفت که هیچ حافظهای ندارد.
این کارخانه شناسه کاربر را از زمینهی اجرا میخواند؛ زمینهای که کد شما مقداردهی میکند. برای ایجنت یک context_schema تعریف کنید و شناسه کاربر را در هر فراخوانی بفرستید:
class Ctx:
user_id: str
…
"per-user": {"ns": lambda rt: ("users", rt.context.user_id), "recall": False, …},
…
backend = CompositeBackend(default=StateBackend(), routes={"/memories/": StoreBackend(namespace=cfg["ns"])})
…
agent = create_deep_agent(model=model, backend=backend, store=store, context_schema=Ctx, system_prompt=SYSTEM, tools=tools, checkpointer=InMemorySaver())
…
context=Ctx(user_id=user), stream_mode="updates", subgraphs=True):چهار بخش برشخورده از کد اجرا. cfg["ns"] همان تابع لامبدای پیکربندی بهازای کاربر است.
دو اعتبارسنج، فضای نام را بررسی میکنند و قواعدشان همخوانی ندارد. StoreBackend حروف، اعداد و کاراکترهای -_.@+:~ را مجاز میداند و کاراکتر * را رد میکند {{code libs/deepagents/deepagents/backends/store.py:44-87}}. در مقابل، خود مخزن وجود کاراکتر . را در هر برچسبی منع میکند. به همین دلیل اگر کارخانهای آدرس ایمیلی مانند carol@acme.com را برمیگرداند، این مقدار از اعتبارسنجی اول رد میشد ولی عملیات نوشتن روی هر دو مخزن با خطای InvalidNamespaceError شکست میخورد. مستندات پیشنهاد میدهد مقدار rt.server_info.user.identity به عنوان برچسب ارسال شود. اگر شناسههای سیستم شما از نوع آدرس ایمیل است، ابتدا هر کدام را به برچسبی بدون نقطه مپ کنید.
ما فراخوانیهای خام مخزن در بخش تفکیک فضای نام را هم یک بار دیگر روی InMemoryStore و PostgresStore اجرا کردیم. با قرار داشتن Alice و Bob ذیل ("users", <user>, ...), این فراخوانیها آیتمها یا فضاهای نامِ هر دو کاربر را برگرداندند: search(("users",))، search(())، list_namespaces() و list_namespaces(prefix=("users", "*")). دستور search(("users", "*", "memories")) هیچ دادهای برنگرداند؛ چون * فقط در متد list_namespaces نویسه عمومی محسوب میشود.
دو نقص در SqliteStore
در طول همین اجراها دو نقص در نگارش 3.1.3 کتابخانهی SqliteStore پیدا شد. این مشکلات نوع ذخیرهسازی دادهها و نحوهی محاسبهی امبدینگها را تغییر میدهند، ولی باعث تداخل دادهی کاربران نمیشوند:
- پس از اجرای متد
delete، ردیف آیتم پاک میشود، اما ردیف متناظر با آن در جدولstore_vectorsباقی میماند: 2 ردیف قبل از حذف و 2 ردیف پس از آن. در تعریف جدول عبارتON DELETE CASCADEآمده است، اماSqliteStoreهرگز کلیدهای خارجی SQLite را فعال نمیکند؛ بنابراین حذف آبشاری اجرا نمیشود. این موضوع در قالب ایشوی باز #8757 ثبت شده است {{issue 8757}}. در نتیجه، جستجو دیگر آن آیتم را برنمیگرداند. - مخزن
SqliteStoreفیلدهای شاخص را از کلیدtext_fieldsمیخواند؛ در حالی کهInMemoryStore،PostgresStoreو داکاسترینگSqliteStoreهمگی ازfieldsاستفاده میکنند {{code libs/checkpoint-sqlite/langgraph/store/sqlite/base.py}}. با تعیینfields=["text"]، این مخزن کل آیتم را امبد کرد و ردیفهای برداری آن فیلد$را گرفتند.
users.alice.memories|k1|$|3072
users.bob.memories|k1|$|3072استفاده از PostgresStore به همراه شاخص به افزونهی pgvector نیاز دارد که پایگاهداده Postgres ما نداشت. این اجرا و همچنین بررسی مجوزهای مخزن در Agent Server، همانطور که در بخش 8.8 آمده است، در ویرایش بعدی بررسی خواهند شد.
منابع: capture/s_persist.py، capture/out/33-store.txt، capture/out/44-store-agent.txt؛ capture/lab/summary/stores-mac.json، capture/lab/T14-stores-mac/01-memory-sqlite.jsonl، capture/lab/T14-stores-mac/02-inmemory-getop-side-effect.txt، capture/lab/T14-stores-mac/03-postgres.jsonl، capture/lab/T14-stores-mac/04-index.jsonl، capture/lab/T14-stores-mac/05-orphan-vectors.txt؛ فایلهای libs/checkpoint/langgraph/store/base/init.py، libs/checkpoint/langgraph/store/memory/init.py، libs/checkpoint-sqlite/langgraph/store/sqlite/base.py و libs/checkpoint-postgres/langgraph/store/postgres/base.py در langgraph 1.2.22؛ docs.langchain.com در کامیت 04d4d4a مستندات (بخشهای oss/python/langgraph/stores و oss/python/langchain/long-term-memory)؛ ایشوی گیتهاب langchain-ai/langgraph#8757 و هشدارهای امنیتی GHSA-47pj-3jcm-6whg و GHSA-6hmw-9432-67qq؛ capture/lab/summary/store-namespace-mac.json، capture/lab/T23-sec-store-namespace-mac/store6_free.json، capture/lab/T23-sec-store-namespace-mac/store6-agent-memory.jsonl، capture/lab/T23-sec-store-namespace-mac/store6-agent-postgres.jsonl؛ libs/deepagents/deepagents/backends/store.py در deepagents 0.7.38؛ docs.langchain.com در کامیت 04d4d4a مستندات (بخش oss/python/deepagents/backends).