{"id":47711986,"url":"https://github.com/zeroasterisk/langgraph-store-vertex-memorybank","last_synced_at":"2026-04-02T18:36:24.398Z","repository":{"id":344116892,"uuid":"1179158841","full_name":"zeroasterisk/langgraph-store-vertex-memorybank","owner":"zeroasterisk","description":"LangGraph BaseStore backed by Vertex AI Agent Engine Memory Bank","archived":false,"fork":false,"pushed_at":"2026-03-21T23:21:02.000Z","size":118,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T10:56:28.180Z","etag":null,"topics":["agent-memory","google-cloud","langgraph","langmem","llm","memory-bank","vertex-ai"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zeroasterisk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-11T18:43:54.000Z","updated_at":"2026-03-21T23:21:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zeroasterisk/langgraph-store-vertex-memorybank","commit_stats":null,"previous_names":["zeroasterisk/langgraph-store-vertex-memorybank"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zeroasterisk/langgraph-store-vertex-memorybank","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeroasterisk%2Flanggraph-store-vertex-memorybank","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeroasterisk%2Flanggraph-store-vertex-memorybank/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeroasterisk%2Flanggraph-store-vertex-memorybank/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeroasterisk%2Flanggraph-store-vertex-memorybank/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zeroasterisk","download_url":"https://codeload.github.com/zeroasterisk/langgraph-store-vertex-memorybank/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeroasterisk%2Flanggraph-store-vertex-memorybank/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31312995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","google-cloud","langgraph","langmem","llm","memory-bank","vertex-ai"],"created_at":"2026-04-02T18:36:23.045Z","updated_at":"2026-04-02T18:36:24.379Z","avatar_url":"https://github.com/zeroasterisk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# langgraph-store-vertex-memorybank\n\nLangGraph [`BaseStore`](https://langchain-ai.github.io/langgraph/reference/store/) backed by [Vertex AI Agent Engine Memory Bank](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/memory-bank/overview) — fully managed, LLM-powered long-term memory.\n\nSwap one line to give any LangGraph agent persistent memory. Works with [langmem](https://langchain-ai.github.io/langmem/) tools out of the box.\n\n```bash\npip install langgraph-store-vertex-memorybank\n```\n\n## Why\n\n| Store | Persists? | Managed? | LLM extraction? |\n|---|---|---|---|\n| `InMemoryStore` | ❌ Lost on restart | — | ❌ |\n| `AsyncPostgresStore` | ✅ | ❌ You run it | ❌ |\n| **`VertexMemoryBankStore`** | ✅ | ✅ Google Cloud | ✅ Extracts, consolidates, deduplicates |\n\n## Two Memory Patterns\n\nThis package supports two complementary patterns for managing long-term memory:\n\n| Pattern | How it works | Best for |\n|---|---|---|\n| **A: langmem tools** | Agent decides what to store via `create_manage_memory_tool` | Explicit, agent-driven memory |\n| **B: GenerateMemories + nodes** | Memory Bank's LLM extracts facts automatically after each conversation | Automatic, implicit, smarter extraction |\n\n**They're complementary.** Use langmem tools when the agent should decide (e.g., \"remember this\"). Use GenerateMemories when you want automatic extraction without the agent needing to think about memory.\n\n## Quick Start\n\n### Pattern A: langmem tools (agent-driven)\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langmem import create_manage_memory_tool, create_search_memory_tool\nfrom langgraph_store_vertex_memorybank import VertexMemoryBankStore\n\nstore = VertexMemoryBankStore(\n    project_id=\"my-project\",\n    location=\"us-central1\",\n    reasoning_engine_id=\"123456\",\n)\n\nagent = create_react_agent(\n    \"google_genai:gemini-2.5-flash\",\n    tools=[\n        create_manage_memory_tool(namespace=(\"memories\",)),\n        create_search_memory_tool(namespace=(\"memories\",)),\n    ],\n    store=store,\n)\n```\n\n### Pattern B: GenerateMemories + nodes (automatic)\n\n```python\nfrom langgraph.graph import StateGraph, START, END\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.graph import MessagesState\nfrom langgraph_store_vertex_memorybank import (\n    VertexMemoryBankStore,\n    create_recall_node,\n    create_capture_node,\n)\n\nstore = VertexMemoryBankStore(\n    project_id=\"my-project\",\n    location=\"us-central1\",\n    reasoning_engine_id=\"123456\",\n)\n\n# Recall injects relevant memories as a SystemMessage before the agent responds.\n# Capture runs generate_memories() in a background thread after the agent responds.\nrecall = create_recall_node(store, recall_mode=\"system\", top_k=5)\ncapture = create_capture_node(store, fire_and_forget=True)\n\ndef agent(state):\n    # your agent logic here\n    ...\n\nbuilder = StateGraph(MessagesState)\nbuilder.add_node(\"recall\", recall)\nbuilder.add_node(\"agent\", agent)\nbuilder.add_node(\"capture\", capture)\nbuilder.add_edge(START, \"recall\")\nbuilder.add_edge(\"recall\", \"agent\")\nbuilder.add_edge(\"agent\", \"capture\")\nbuilder.add_edge(\"capture\", END)\n\ngraph = builder.compile()\ngraph.invoke(\n    {\"messages\": [(\"user\", \"I just moved to Portland\")]},\n    {\"configurable\": {\"user_id\": \"alice\"}},\n)\n```\n\n### Direct usage\n\n```python\nfrom langgraph_store_vertex_memorybank import VertexMemoryBankStore\n\nstore = VertexMemoryBankStore(\n    project_id=\"my-project\",\n    location=\"us-central1\",\n    reasoning_engine_id=\"123456\",\n)\n\nns = (\"memories\", \"user_id\", \"alice\")\n\nstore.put(ns, \"pref-1\", {\"fact\": \"Prefers dark mode\"})\n\nresults = store.search(ns, query=\"What theme?\", limit=5)\nfor r in results:\n    print(f\"[{r.score:.2f}] {r.value['fact']}\")\n```\n\n## Memory Generation\n\n`generate_memories()` is Memory Bank's killer feature. Unlike `put()` (which stores exactly what you give it), `generate_memories()` uses an LLM to:\n\n- **Extract** meaningful facts from conversation turns\n- **Consolidate** with existing memories — deduplicating and updating\n- **Delete** contradicted information automatically\n\n```python\n# Direct usage\nevents = [\n    {\"content\": {\"role\": \"user\", \"parts\": [{\"text\": \"I just moved to Portland from NYC\"}]}},\n    {\"content\": {\"role\": \"model\", \"parts\": [{\"text\": \"Welcome to Portland!\"}]}},\n]\nstore.generate_memories(scope={\"user_id\": \"alice\"}, events=events)\n```\n\nThe `create_capture_node()` helper wraps this into a LangGraph node that automatically converts messages and runs generation in a background thread (fire-and-forget) so it doesn't block the response.\n\nThe `create_recall_node()` helper searches memories using the last user message and injects them as a `SystemMessage` (or state field) before the agent responds.\n\n## Architecture\n\n```\n┌─ Pattern A ──────────────────────┐  ┌─ Pattern B ───────────────────────┐\n│ langmem tools                    │  │ recall_node → agent → capture_node│\n│ (agent decides what to store)    │  │ (automatic LLM extraction)        │\n└──────────────┬───────────────────┘  └──────────────┬────────────────────┘\n               ↓                                     ↓\n        LangGraph BaseStore                  generate_memories()\n        batch([GetOp, SearchOp, ...])        (Memory Bank extension)\n               ↓                                     ↓\n         VertexMemoryBankStore  ←── this package ──────┘\n               ↓\n    google-cloud-aiplatform SDK  ← handles auth, retries, pagination\n               ↓\n      Vertex AI Memory Bank  ← managed service\n```\n\n## Namespace ↔ Scope Mapping\n\nLangGraph uses namespace tuples. Memory Bank uses scope dicts. This package maps between them:\n\n```python\n# Basic: user-scoped\n(\"memories\", \"user_id\", \"alice\")\n  → scope: {\"user_id\": \"alice\"}\n\n# With topic filter\n(\"memories\", \"user_id\", \"alice\", \"topic\", \"preferences\")\n  → scope: {\"user_id\": \"alice\"}, filter: topic=\"preferences\"\n\n# Multi-key\n(\"memories\", \"user_id\", \"alice\", \"session\", \"s1\")\n  → scope: {\"user_id\": \"alice\", \"session\": \"s1\"}\n```\n\nNamespaces are parsed as alternating key-value pairs after the prefix. The special key `\"topic\"` adds a server-side filter instead of a scope entry.\n\n## BaseStore Interface\n\nImplements the full [LangGraph BaseStore](https://langchain-ai.github.io/langgraph/reference/store/) contract:\n\n| Method | Memory Bank SDK call |\n|---|---|\n| `search(ns, query)` | `memories.retrieve(similarity_search_params)` |\n| `put(ns, key, value)` | `memories.create(fact, scope)` |\n| `get(ns, key)` | `memories.get(name)` |\n| `put(ns, key, None)` | `memories.delete(name)` |\n| `list_namespaces()` | `memories.list()` → extract unique scopes |\n| `batch(ops)` / `abatch(ops)` | Dispatches to above |\n| `generate_memories(scope, events)` | `memories.generate(...)` *(extension)* |\n\nDistance is converted to similarity: `score = 1 / (1 + distance)`.\n\nResults below `min_similarity_score` (default 0.3) are filtered out.\n\n## Configuration\n\n```python\nstore = VertexMemoryBankStore(\n    project_id=\"my-project\",        # required\n    location=\"us-central1\",         # required\n    reasoning_engine_id=\"123456\",   # required\n    client=None,                    # optional pre-configured vertexai.Client\n    namespace_prefix=\"memories\",    # prefix for namespace tuples\n    default_top_k=10,               # default search result count\n    min_similarity_score=0.3,       # similarity floor\n)\n```\n\nPass an existing `vertexai.Client` to share connections across stores.\n\n## Prerequisites\n\n1. Python ≥ 3.10\n2. A Google Cloud project with [Vertex AI API](https://console.cloud.google.com/apis/api/aiplatform.googleapis.com) enabled\n3. An Agent Engine instance for Memory Bank — [setup guide](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/memory-bank/set-up)\n4. Authentication via [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials):\n   ```bash\n   gcloud auth application-default login\n   ```\n\n## Development\n\n```bash\ngit clone https://github.com/zeroasterisk/langgraph-store-vertex-memorybank.git\ncd langgraph-store-vertex-memorybank\nuv sync --extra dev\n\n# Unit tests (mocked, no GCP needed)\nuv run pytest -m \"not integration\" -v\n\n# Integration tests (needs ADC + Memory Bank instance)\nuv run pytest -m integration -v\n```\n\n## References\n\n- **Memory Bank overview**: https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/memory-bank/overview\n- **Memory Bank quickstart (ADK)**: https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/memory-bank/quickstart-adk\n- **Memory Bank quickstart (API)**: https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/memory-bank/quickstart-api\n- **Official LangGraph notebook**: https://github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/agent-engine/memory/get_started_with_memory_bank_langgraph.ipynb\n- **Official CrewAI notebook**: https://github.com/GoogleCloudPlatform/generative-ai/blob/main/gemini/agent-engine/memory/get_started_with_memory_bank_crewai.ipynb\n- **LangGraph long-term memory concepts**: https://langchain-ai.github.io/langgraph/concepts/memory/\n- **langmem documentation**: https://langchain-ai.github.io/langmem/\n- **LangGraph BaseStore reference**: https://langchain-ai.github.io/langgraph/reference/store/\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeroasterisk%2Flanggraph-store-vertex-memorybank","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeroasterisk%2Flanggraph-store-vertex-memorybank","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeroasterisk%2Flanggraph-store-vertex-memorybank/lists"}