Metadata-Version: 2.5
Name: langgraph-store-dynamodb
Version: 0.2.0
Summary: Amazon DynamoDB long-term-memory store (BaseStore) for LangGraph — namespaced key/value memory with prefix search, filters, list_namespaces and native semantic (vector) search
Project-URL: Homepage, https://github.com/skamalj/langgraph-store
Project-URL: Repository, https://github.com/skamalj/langgraph-store.git
Project-URL: Documentation, https://skamalj.github.io/agentstate-reducer/
Author-email: Kamal <skamalj@gmail.com>
Keywords: agent-memory,aws,basestore,dynamodb,langgraph,long-term-memory,semantic-search,store,vector-search
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: boto3>=1.43.78
Requires-Dist: langgraph-store-core>=0.1.0
Description-Content-Type: text/markdown

# langgraph-store-dynamodb

Amazon DynamoDB **long-term-memory store** (`BaseStore`) for [LangGraph](https://langchain-ai.github.io/langgraph/) — namespaced key/value agent memory with prefix search, Mongo-style filters, `list_namespaces`, sync + async, and **native semantic search** via DynamoDB vector search.

```bash
pip install langgraph-store-dynamodb
```

## Usage

```python
from langgraph_store_dynamodb import DynamoDBStore

store = DynamoDBStore(table_name="langgraph-store")          # table auto-created (PAY_PER_REQUEST)

store.put(("users", "1", "memories"), "food", {"text": "loves sushi", "kind": "pref"})
item  = store.get(("users", "1", "memories"), "food")
hits  = store.search(("users", "1"), filter={"kind": "pref"}, limit=10)
spaces = store.list_namespaces(prefix=("users",))

graph = builder.compile(store=store)                          # as a LangGraph store
```

### Semantic search (DynamoDB native vector search)

Pass a LangGraph `IndexConfig` and the store embeds the configured fields on `put` and ranks `search(query=...)` by cosine similarity using DynamoDB's `SearchVectors` — no external vector database.

```python
from langgraph_store_core import bedrock_titan_embeddings
from langgraph_store_dynamodb import DynamoDBStore

store = DynamoDBStore(
    table_name="langgraph-memory",
    index={"dims": 1024, "embed": bedrock_titan_embeddings(dimensions=1024), "fields": ["text"]},
)
store.put(("memories", "kamal"), "k1", {"text": "the user loves sushi", "kind": "pref"})
hits = store.search(("memories", "kamal"), query="what food does the user like?", filter={"kind": "pref"})
print(hits[0].score, hits[0].value)
```

`embed` may be any LangChain `Embeddings`, a `list[str] -> list[list[float]]` callable, or a provider string. `fields` defaults to `["$"]` (the whole value as JSON). `put(..., index=False)` skips embedding for one item; `put(..., index=["title"])` overrides the fields.

The table is created with a vector index (`embedding`, cosine, `dims`, `PK` as an inline filter). A vector index can only be declared at table creation, so use a **new table name** when enabling semantic search on an existing store. `SearchConditionExpression` only allows equality on a string search-schema attribute, so a prefix search resolves to its concrete namespaces (keys-only scan) and runs one ANN query per namespace, merged by score — an exact namespace is a single call. Value `filter`s cannot be expressed there (only top-level search-schema attributes), so the store oversamples and applies them on the returned candidates.

Requires `boto3>=1.43.78` and a region where DynamoDB vector search is available (GA 2026-08-05). Bedrock model access is needed only for the default Titan embedder.

## Upgrading from 0.1.x

0.2.0 is a rewrite on [`langgraph-store-core`](https://pypi.org/project/langgraph-store-core/). Same table (`PK` = namespace, `SK` = key, `value`, `created_at`, `updated_at`), same constructor (`max_read_request_units` / `max_write_request_units` still accepted). New in 0.2.0: prefix search (not just exact namespace), `filter`, `offset`, `list_namespaces`, `GetOp`/`ListNamespacesOp` in `batch`, ordered `abatch`, semantic search, and `region_name` / `boto_session` / `endpoint_url` options. Namespaces are now joined with a unit separator instead of `:`; items written by 0.1.x are still read and are migrated on their next `put`. `aioboto3` is no longer required.

## AWS permissions

`dynamodb:DescribeTable`, `CreateTable`, `GetItem`, `PutItem`, `DeleteItem`, `Query`, `Scan`, and `SearchVectors` (for semantic search), plus `bedrock:InvokeModel` for the default embedder.

## License

MIT · part of the [langgraph-store](https://github.com/skamalj/langgraph-store) family · docs: <https://skamalj.github.io/agentstate-reducer/>
