langgraph-dynamodb-store 0.1.0__py3-none-any.whl

langgraph_dynamodb_store-0.1.0.dist-info/METADATA

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: langgraph-dynamodb-store
+Version: 0.1.0
+Summary: A DynamoDB-backed BaseStore for LangGraph — cross-thread memory for agents, no Postgres/pgvector required
+Project-URL: Homepage, https://github.com/mauriciosneira/memory-layer
+Project-URL: Issues, https://github.com/mauriciosneira/memory-layer/issues
+Author: Mauricio Neira
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,dynamodb,langchain,langgraph,llm,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: boto3>=1.35
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langgraph>=0.2
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: moto[dynamodb]>=5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: semantic
+Requires-Dist: langchain-openai>=0.2; extra == 'semantic'
+Requires-Dist: numpy>=1.26; extra == 'semantic'
+Description-Content-Type: text/markdown
+
+# memory-layer
+
+[![Tests](https://github.com/mauriciosneira/memory-layer/actions/workflows/test.yml/badge.svg)](https://github.com/mauriciosneira/memory-layer/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**A DynamoDB-backed `BaseStore` for LangGraph — cross-thread memory for your agents without standing up Postgres/pgvector.**
+
+LangGraph's checkpointer persists state *inside* a thread — when a user opens a new conversation, the graph starts from zero. The `store` protocol is LangGraph's answer to that: memory that survives *across* threads, shared by every session for the same user (or the same tenant). LangGraph ships an official store for Postgres. If your stack is already DynamoDB — which a lot of serverless/Fargate deployments are — there wasn't an official option. `memory-layer` is that option.
+
+```python
+from memory_layer import DynamoDBStore
+
+store = DynamoDBStore(table_name="my-app-memories")
+graph = builder.compile(checkpointer=checkpointer, store=store)
+```
+
+That's the whole integration. No new infra beyond one DynamoDB table you probably already know how to provision.
+
+---
+
+## Why this exists
+
+- **You're already on DynamoDB.** Adding Postgres + pgvector just for agent memory is a real infra cost — a new engine, a new backup story, a new thing to monitor — for a feature that, for most products, doesn't need vector search on day one.
+- **LangGraph's `store` protocol is a clean seam.** It's designed so storage is swappable — your agent code shouldn't care whether memories live in Postgres, Dynamo, or Redis. This fills the Dynamo gap in that seam.
+- **Memory doesn't have to mean embeddings.** Most products get real value from "the last N things we know about this user," fetched by recency — no vector index required. `memory-layer` starts there, and gives you a clean place to add semantic ranking later if you actually need it.
+
+## Features
+
+- **`DynamoDBStore`** — a complete `langgraph.store.base.BaseStore` implementation: `get`/`put`/`search` (and their async counterparts), real pagination via DynamoDB's `LastEvaluatedKey` (not a "hope the first page has enough" heuristic), per-item filtering, and per-type TTL (e.g. auto-expire `episodic` memories after 90 days while `semantic` ones never expire).
+- **`SimpleRetrieval`** — fetch a user's N most recent memories and turn them into a ready-to-inject prompt block. No embeddings, no extra dependencies.
+- **`MemoryWriter`** — an LLM-driven extraction step: hand it a conversation, it classifies and persists the facts worth remembering, via `with_structured_output` (a real schema-validated response, not a hand-rolled JSON parser hoping the model didn't wrap the array in a sentence).
+- **Scopes, not just users.** Namespaces are plain tuples (`("user", user_id)`, `("instance", tenant_id)`) — model per-user memory, per-tenant shared context, or your own scope, however your product actually shapes ownership.
+
+## Install
+
+```bash
+pip install langgraph-dynamodb-store
+```
+
+Want LLM-driven extraction? `MemoryWriter` takes any LangChain `BaseChatModel` — bring the one you already use, no extra install needed. `numpy`/`langchain-openai` are only required for the semantic-retrieval extra (see [Roadmap](#roadmap)):
+
+```bash
+pip install "langgraph-dynamodb-store[semantic]"
+```
+
+## DynamoDB table
+
+One table, one GSI. Create it however you provision infra (CDK/Terraform/console) — here's the raw shape via the AWS CLI, if you just want to try it out:
+
+```bash
+aws dynamodb create-table \
+  --table-name my-app-memories \
+  --attribute-definitions \
+      AttributeName=owner_id,AttributeType=S \
+      AttributeName=memory_id,AttributeType=S \
+      AttributeName=created_at,AttributeType=S \
+  --key-schema \
+      AttributeName=owner_id,KeyType=HASH \
+      AttributeName=memory_id,KeyType=RANGE \
+  --global-secondary-indexes '[{
+      "IndexName": "owner_id-created_at-index",
+      "KeySchema": [
+          {"AttributeName": "owner_id", "KeyType": "HASH"},
+          {"AttributeName": "created_at", "KeyType": "RANGE"}
+      ],
+      "Projection": {"ProjectionType": "ALL"}
+  }]' \
+  --billing-mode PAY_PER_REQUEST
+
+# Optional but recommended — lets episodic memories actually expire instead of
+# accumulating forever. memory-layer sets the `ttl` attribute; DynamoDB does the rest.
+aws dynamodb update-time-to-live \
+  --table-name my-app-memories \
+  --time-to-live-specification "Enabled=true, AttributeName=ttl"
+```
+
+Set `MEMORY_TABLE=my-app-memories` or pass `table_name` explicitly — `DynamoDBStore(table_name="my-app-memories")`.
+
+## Quickstart
+
+```python
+from memory_layer import DynamoDBStore
+
+store = DynamoDBStore(table_name="my-app-memories")
+
+namespace = ("user", "user-123")
+
+store.put(namespace, "mem-1", {"content": "Prefers responses in Spanish", "type": "semantic"})
+store.put(namespace, "mem-2", {"content": "Reviewed Q3 numbers on 2026-08-01", "type": "episodic"})
+
+memories = store.search(namespace, limit=10)
+for m in memories:
+    print(m.value["content"])
+```
+
+### Inside a LangGraph node
+
+LangGraph injects `store` into any node whose signature asks for it:
+
+```python
+from langgraph.store.base import BaseStore
+from langchain_core.runnables import RunnableConfig
+
+from memory_layer import DynamoDBStore
+from memory_layer.retrieval import SimpleRetrieval
+
+store = DynamoDBStore(table_name="my-app-memories")
+graph = builder.compile(checkpointer=checkpointer, store=store)
+
+def supervisor_node(state: AgentState, config: RunnableConfig, store: BaseStore) -> dict:
+    user_id = state["context"]["user_id"]
+    retrieval = SimpleRetrieval(store, limit=5)
+    memories = retrieval.fetch(("user", user_id))
+    memory_block = retrieval.to_prompt_block(memories)
+    # ...inject memory_block into the system prompt
+    return {}
+```
+
+### Writing memories back
+
+```python
+from memory_layer.writer import MemoryWriter
+
+writer = MemoryWriter(llm=your_chat_model, store=store)
+
+async def memory_writer_node(state: AgentState) -> dict:
+    await writer.extract_and_save(
+        namespace=("user", state["context"]["user_id"]),
+        messages=state["messages"],
+        session_id=state["context"]["session_id"],
+    )
+    return {}
+```
+
+The extraction LLM only needs `with_structured_output` support — every major provider's LangChain integration has it.
+
+## Memory types
+
+| Type | What it's for | Default TTL |
+|---|---|---|
+| `semantic` | Stable preferences and facts ("prefers Spanish", "works on the Acme account") | none |
+| `episodic` | Specific past events ("reviewed Q3 numbers on 2026-08-01") | 90 days |
+| `procedural` | Recurring work patterns ("always starts with a channel breakdown") | none |
+
+TTL policy per type lives in `memory_layer.store._TTL_SECONDS_BY_TYPE` — override it if 90 days isn't the right default for your product.
+
+## Scopes
+
+A namespace is just a tuple — `memory-layer` doesn't prescribe what it means, but the common shapes are:
+
+```python
+("user", cognito_sub)        # private to one user
+("instance", tenant_id)      # shared across every user of one tenant
+```
+
+## Roadmap
+
+- **Semantic retrieval** — embed memories + query, rank by cosine similarity, for products that outgrow "most recent N" (roughly ~20+ memories per user is where this starts to matter). Lives behind the `semantic` extra so the core library stays dependency-light.
+- **Deduplication on write** — skip persisting a fact that's a near-duplicate of one already stored.
+- **Bring-your-own embeddings backend** — DynamoDB-native cosine similarity to start; pluggable enough to swap in pgvector/a real vector store later if volume ever justifies it.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run against [`moto`](https://github.com/getmoto/moto) — no real AWS account or network access required.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

langgraph_dynamodb_store-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+memory_layer/__init__.py,sha256=axH8XyMwwTLz3fgKeZzaBN14Pn6ZLtry-_482sGj8FI,163
+memory_layer/retrieval.py,sha256=vEl94VUmrcg6upkazyk4Ru6yBP4vSj4SVT2OOyhVpVo,1144
+memory_layer/store.py,sha256=1xsJguNy31-z88KClBalznPGX_5secCDa2WGRDPUNT8,5744
+memory_layer/types.py,sha256=NsYpvjnicO-bjIiWWcIRfO3sxgpPDuMPB8pf6gGLX3w,356
+memory_layer/writer.py,sha256=Rgx4ko9WnF3Of4dtfAElJUur3gsJZq6Kp9v_f70pb3g,2603
+langgraph_dynamodb_store-0.1.0.dist-info/METADATA,sha256=06rbdrq9nLs8Rlq12lYCkf8ZPSzXzZakmDYrsC4sgFY,9199
+langgraph_dynamodb_store-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+langgraph_dynamodb_store-0.1.0.dist-info/licenses/LICENSE,sha256=f9c-ka2i0rKaqbPVdW-9crUoQtg68EOKK9MoHORUs3I,1071
+langgraph_dynamodb_store-0.1.0.dist-info/RECORD,,

langgraph_dynamodb_store-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

langgraph_dynamodb_store-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mauricio Neira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memory_layer/__init__.py

@@ -0,0 +1,4 @@
+from .store import DynamoDBStore
+from .types import MemoryRecord, MemoryType, MemoryScope
+
+__all__ = ["DynamoDBStore", "MemoryRecord", "MemoryType", "MemoryScope"]

memory_layer/retrieval.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from langgraph.store.base import BaseStore, SearchItem
+
+
+class SimpleRetrieval:
+    """Fetches N most recent memories by recency. No embeddings required."""
+
+    def __init__(self, store: BaseStore, limit: int = 10) -> None:
+        self._store = store
+        self._limit = limit
+
+    def fetch(
+        self,
+        namespace: tuple[str, ...],
+        *,
+        memory_type: str | None = None,
+    ) -> list[SearchItem]:
+        filter_ = {"type": memory_type} if memory_type else None
+        return self._store.search(namespace, filter=filter_, limit=self._limit)
+
+    async def afetch(
+        self,
+        namespace: tuple[str, ...],
+        *,
+        memory_type: str | None = None,
+    ) -> list[SearchItem]:
+        filter_ = {"type": memory_type} if memory_type else None
+        return await self._store.asearch(namespace, filter=filter_, limit=self._limit)
+
+    def to_prompt_block(self, memories: list[SearchItem]) -> str:
+        if not memories:
+            return ""
+        lines = "\n".join(f"- {m.value.get('content', '')}" for m in memories)
+        return f"## User memory\n{lines}"

memory_layer/store.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from datetime import datetime, timezone
+from typing import Any, Iterable
+
+import boto3
+from boto3.dynamodb.conditions import Key
+from langgraph.store.base import (
+    BaseStore,
+    GetOp,
+    Item,
+    ListNamespacesOp,
+    Op,
+    PutOp,
+    Result,
+    SearchItem,
+    SearchOp,
+)
+
+_TABLE_NAME = os.environ.get("MEMORY_TABLE", "memory-layer-local-memories")
+_MAX_SEARCH_PAGES = 10
+_TTL_SECONDS_BY_TYPE = {"episodic": 90 * 24 * 60 * 60}  # semantic/procedural: no ttl attribute, never expire
+
+
+def _owner_id(namespace: tuple[str, ...]) -> str:
+    return ":".join(namespace)
+
+
+def _parse_namespace(owner_id: str) -> tuple[str, ...]:
+    return tuple(owner_id.split(":"))
+
+
+def _row_to_item(row: dict[str, Any]) -> Item:
+    return Item(
+        namespace=_parse_namespace(row["owner_id"]),
+        key=row["memory_id"],
+        value=json.loads(row["value"]),
+        created_at=datetime.fromisoformat(row["created_at"]),
+        updated_at=datetime.fromisoformat(row["updated_at"]),
+    )
+
+
+def _row_to_search_item(row: dict[str, Any]) -> SearchItem:
+    return SearchItem(
+        namespace=_parse_namespace(row["owner_id"]),
+        key=row["memory_id"],
+        value=json.loads(row["value"]),
+        created_at=datetime.fromisoformat(row["created_at"]),
+        updated_at=datetime.fromisoformat(row["updated_at"]),
+        score=None,
+    )
+
+
+def _matches_filter(value: dict[str, Any], filter: dict[str, Any]) -> bool:
+    for field, condition in filter.items():
+        field_val = value.get(field)
+        if isinstance(condition, dict):
+            for op, operand in condition.items():
+                if op == "$eq" and field_val != operand:
+                    return False
+                elif op == "$ne" and field_val == operand:
+                    return False
+                elif op == "$gt" and not (field_val is not None and field_val > operand):
+                    return False
+                elif op == "$gte" and not (field_val is not None and field_val >= operand):
+                    return False
+                elif op == "$lt" and not (field_val is not None and field_val < operand):
+                    return False
+                elif op == "$lte" and not (field_val is not None and field_val <= operand):
+                    return False
+        elif field_val != condition:
+            return False
+    return True
+
+
+class DynamoDBStore(BaseStore):
+    def __init__(self, table_name: str = _TABLE_NAME) -> None:
+        self._table = boto3.resource("dynamodb").Table(table_name)
+
+    def batch(self, ops: Iterable[Op]) -> list[Result]:
+        results: list[Result] = []
+        for op in ops:
+            if isinstance(op, GetOp):
+                results.append(self._handle_get(op))
+            elif isinstance(op, PutOp):
+                results.append(self._handle_put(op))
+            elif isinstance(op, SearchOp):
+                results.append(self._handle_search(op))
+            elif isinstance(op, ListNamespacesOp):
+                results.append([])
+            else:
+                raise TypeError(f"Unsupported op type: {type(op).__name__}")
+        return results
+
+    async def abatch(self, ops: Iterable[Op]) -> list[Result]:
+        return await asyncio.to_thread(self.batch, list(ops))
+
+    def _handle_get(self, op: GetOp) -> Item | None:
+        resp = self._table.get_item(
+            Key={"owner_id": _owner_id(op.namespace), "memory_id": op.key}
+        )
+        row = resp.get("Item")
+        return _row_to_item(row) if row else None
+
+    def _handle_put(self, op: PutOp) -> None:
+        pk = {"owner_id": _owner_id(op.namespace), "memory_id": op.key}
+        if op.value is None:
+            self._table.delete_item(Key=pk)
+            return
+
+        now = datetime.now(timezone.utc).isoformat()
+        update_expression = (
+            "SET #v = :v, updated_at = :now, "
+            "created_at = if_not_exists(created_at, :now)"
+        )
+        expression_values: dict[str, Any] = {":v": json.dumps(op.value), ":now": now}
+
+        ttl_seconds = _TTL_SECONDS_BY_TYPE.get(op.value.get("type"))
+        if ttl_seconds is not None:
+            update_expression += ", #ttl = :ttl"
+            expression_values[":ttl"] = int(datetime.now(timezone.utc).timestamp()) + ttl_seconds
+
+        self._table.update_item(
+            Key=pk,
+            UpdateExpression=update_expression,
+            ExpressionAttributeNames={"#v": "value", "#ttl": "ttl"} if ttl_seconds is not None else {"#v": "value"},
+            ExpressionAttributeValues=expression_values,
+        )
+
+    def _handle_search(self, op: SearchOp) -> list[SearchItem]:
+        matches: list[dict[str, Any]] = []
+        last_evaluated_key: dict[str, Any] | None = None
+        pages = 0
+
+        while len(matches) < op.offset + op.limit and pages < _MAX_SEARCH_PAGES:
+            query_kwargs: dict[str, Any] = {
+                "IndexName": "owner_id-created_at-index",
+                "KeyConditionExpression": Key("owner_id").eq(_owner_id(op.namespace_prefix)),
+                "ScanIndexForward": False,
+            }
+            if last_evaluated_key is not None:
+                query_kwargs["ExclusiveStartKey"] = last_evaluated_key
+
+            resp = self._table.query(**query_kwargs)
+            rows = resp.get("Items", [])
+            pages += 1
+
+            if op.filter:
+                rows = [r for r in rows if _matches_filter(json.loads(r["value"]), op.filter)]
+            matches.extend(rows)
+
+            last_evaluated_key = resp.get("LastEvaluatedKey")
+            if last_evaluated_key is None:
+                break
+
+        return [_row_to_search_item(r) for r in matches[op.offset : op.offset + op.limit]]

memory_layer/types.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+from typing import Literal, TypedDict, Optional
+
+
+MemoryType = Literal["semantic", "episodic", "procedural"]
+MemoryScope = Literal["user", "instance"]
+
+
+class MemoryRecord(TypedDict, total=False):
+    content: str
+    type: MemoryType
+    created_at: str
+    updated_at: str
+    session_id: str
+    score: Optional[float]

memory_layer/writer.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from uuid import uuid4
+
+from langchain_core.messages import BaseMessage, SystemMessage, HumanMessage
+from langchain_core.language_models import BaseChatModel
+from langgraph.store.base import BaseStore
+from pydantic import BaseModel
+
+from .types import MemoryType
+
+_EXTRACTION_PROMPT = """You are a memory extraction assistant. Given a conversation, extract facts worth remembering about the user for future sessions.
+
+Rules:
+- Only extract facts that would be useful in a *future* conversation — preferences, recurring patterns, key domain context.
+- Ignore facts that are specific to this single request and won't generalise.
+- Each fact must be a short, standalone sentence.
+- Classify each fact as one of: semantic (preferences/facts about the user), episodic (specific past event), procedural (recurring work pattern).
+- If nothing is worth remembering, return no facts."""
+
+
+class _ExtractedFact(BaseModel):
+    content: str
+    type: MemoryType
+
+
+class _ExtractedFacts(BaseModel):
+    facts: list[_ExtractedFact]
+
+
+class MemoryWriter:
+    def __init__(self, llm: BaseChatModel, store: BaseStore) -> None:
+        self._llm = llm
+        self._store = store
+
+    async def extract_and_save(
+        self,
+        namespace: tuple[str, ...],
+        messages: list[BaseMessage],
+        session_id: str,
+    ) -> int:
+        conversation = _format_conversation(messages)
+        if not conversation:
+            return 0
+
+        extraction_messages = [
+            SystemMessage(content=_EXTRACTION_PROMPT),
+            HumanMessage(content=conversation),
+        ]
+        # with_structured_output validates the shape via the provider's own tool-calling —
+        # no hand-rolled JSON parsing, no risk of a stray sentence around the array breaking it.
+        structured_llm = self._llm.with_structured_output(_ExtractedFacts)
+        result: _ExtractedFacts = await structured_llm.ainvoke(extraction_messages)
+
+        for fact in result.facts:
+            await self._store.aput(
+                namespace,
+                str(uuid4()),
+                {
+                    "content": fact.content,
+                    "type": fact.type,
+                    "session_id": session_id,
+                },
+            )
+
+        return len(result.facts)
+
+
+def _format_conversation(messages: list[BaseMessage]) -> str:
+    lines: list[str] = []
+    for msg in messages:
+        role = getattr(msg, "type", "unknown")
+        if role in ("human", "ai") and msg.content:
+            lines.append(f"{role.upper()}: {msg.content}")
+    return "\n".join(lines)