Ask shape	Primary answer	Why
Generic conversation continuity — “remember what we discussed”, last-N messages, session summaries, TTL	Amazon Bedrock AgentCore Memory (fully managed) or DynamoDB with TTL for a lightweight custom store	These are session/short-term stores; adding Neptune for a simple recall requirement is over-engineering
Relationship-heavy / multi-hop memory — entity → entity traversal, cross-session facts, GraphRAG over the memory graph	Amazon Neptune property-graph memory (User → Conversation → Entity → Fact)	Structured relationships compound over time; graph traversal beats flat logs
Hybrid — short-term recall + long-term structured memory	Both: AgentCore/DynamoDB for last-N and TTL + Neptune for the entity/fact graph	Layered memory stack

The rest of this document covers the Neptune property-graph pattern — how to model, store, and retrieve entity/fact memory when the ask is relationship-heavy or when you need the long-term layer of a hybrid stack. Do not apply this pattern for generic conversation continuity alone.

Complementary layers of the memory stack:

Service	Role in the stack
Bedrock AgentCore Memory	Fully managed short-term + session-summary recall
Bedrock Agents `memoryId`	Session summaries within a single agent workflow
DynamoDB	Session state store, TTL-based expiry, short-term transcript
LangChain `ConversationBufferMemory`	In-process buffer for the in-flight conversation

Overview

AI agents need memory to maintain context across interactions:

Short-term memory (session, recent messages) → DynamoDB (TTL auto-expire)
Long-term memory (entities, relationships, knowledge) → Neptune

Neptune excels at long-term memory because agent knowledge is a graph — entities relate to entities, conversations reference topics, knowledge compounds through connections.

Neptune Database — persistent, always-on, millisecond reads. Production agents. Neptune Analytics — built-in vector search (graph + vectors, no separate store). Prototyping or agents needing semantic recall.

Security: Agent memory graphs may contain sensitive entity relationships and embedding vectors. Neptune Analytics is always encrypted at rest (AWS-managed or customer-managed KMS key). DynamoDB tables are already encrypted at rest by default (AWS-owned key); for sensitive agent memory, upgrade to KMS-managed encryption (SSESpecification: {SSEEnabled: true, SSEType: 'KMS'}) to gain key-rotation control and CloudTrail key-usage logging. Also enable KMS encryption on any CloudWatch Logs groups that store agent-memory data and any SNS topics used for notifications — these can contain sensitive context (entity relationships, embeddings, facts) and must be protected with the same care as the graph itself.

Neptune MCP Servers for Agent Integration

Neptune provides two MCP (Model Context Protocol) servers that give agents direct access to Neptune capabilities:

Neptune MCP Query Server — lets agents run openCypher and Gremlin queries against Neptune Database and Neptune Analytics, and fetch graph schema. Use this when your agent needs to query an existing graph as part of its workflow.
Neptune MCP Memory Server — provides persistent memory to agents, storing knowledge graphs against Neptune. Use this when your agent needs to remember entities, relationships, and facts across sessions.

These MCP servers integrate with agent frameworks like Strands AI Agents SDK and other MCP-compatible tools. They complement this skill: the skill provides guidance on what to build, the MCP servers provide runtime tools for agents to use what’s built.

Architecture

┌─────────────────────────────────────────────┐
│  AI Agent                                   │
│  ┌─────────────┐  ┌──────────────────────┐ │
│  │ Short-Term  │  │ Long-Term Memory     │ │
│  │ (DynamoDB)  │  │ (Neptune)            │ │
│  │ • Session   │  │ • Entity graph       │ │
│  │ • Last N    │  │ • Episodic memory    │ │
│  │ • TTL 24h   │  │ • Vector index (Ana) │ │
│  └─────────────┘  └──────────────────────┘ │
└─────────────────────────────────────────────┘

Graph Model

(Entity {name, type, description, confidence, updated_at})
(Conversation {id, user_id, date, summary})
(Fact {content, confidence, created_at})

(Entity) -[RELATED_TO {type, confidence}]→ (Entity)
(Conversation) -[ABOUT]→ (Entity)
(Fact) -[LEARNED_IN]→ (Conversation)

Implementation

Full helpers in scripts/agentic_memory.py. Key patterns:

Short-term (DynamoDB)

from scripts.agentic_memory import store_message, get_recent_messages

store_message(session_id='sess-123', role='user', content='Tell me about Alice')
messages = get_recent_messages(session_id='sess-123', limit=20)

Long-term — Neptune Database (Gremlin, persistent)

from scripts.agentic_memory import (
    get_gremlin_client, remember_entity_gremlin,
    remember_relationship_gremlin, recall_entity_gremlin
)

client = get_gremlin_client()
remember_entity_gremlin(client, 'Alice', 'Person')
remember_relationship_gremlin(client, 'Alice', 'Acme Corp', 'WORKS_AT')
memory = recall_entity_gremlin(client, 'Alice')

Uses Gremlin bindings (parameterized) — no string interpolation.

Long-term — Neptune Analytics (openCypher + vector)

from scripts.agentic_memory import (
    remember_with_embedding, semantic_recall, hybrid_recall
)

# Store with embedding
remember_with_embedding(graph_id, 'Alice', 'Engineer at Acme', embedding_vector)

# Recall by similarity
results = semantic_recall(graph_id, query_embedding, top_k=10)

# Hybrid: graph traversal + vector search
context = hybrid_recall(graph_id, 'Alice', query_embedding)

Memory consolidation

from scripts.agentic_memory import consolidate_memories
consolidate_memories(graph_id)  # Decay old facts, remove low-confidence

Persistence Strategy (Critical for Analytics)

Neptune Analytics is ephemeral. For production agents:

Strategy	Tradeoff
Periodic S3 export	Cost-efficient, some data loss risk
Dual-write to Neptune Database	Zero loss, higher cost
Database as source, sync to Analytics	Best durability
Event-sourced (log to DynamoDB/S3)	Full audit trail, rebuild from scratch

Recommended: Neptune Database for persistence + Analytics only if you need vector search.

Common Mistakes

Storing everything — use LLM extraction to filter noise
No memory decay — implement confidence decay + periodic cleanup
Vector-only recall — graph traversal finds structural connections vectors miss
Separate vector store with Analytics — Analytics has built-in vectors
No timestamps — agents need temporal context for relevance
No persistence strategy — Analytics memory is lost on graph deletion
String interpolation — use parameterized queries (bindings or $param)

Memory Framework Integrations

Neptune is the graph backend for three major agent memory frameworks. These provide higher-level abstractions over Neptune for teams that want memory capabilities without building from scratch:

Mem0 — self-improving memory layer for AI agents. Neptune as graph store for entity relationships and knowledge accumulation.
Cognee — agentic memory framework. Neptune as graph store for structured knowledge that agents build over time.
Zep — long-term interaction history for agents. Neptune as graph store for conversation-derived entity relationships.

These frameworks handle entity extraction, relationship management, and memory consolidation. Use them when you want production-ready agent memory without building the graph ingestion pipeline yourself. Use the custom implementation (above) when you need full control over the graph model and memory architecture.

Additional Resources

Script: scripts/agentic_memory.py (full implementation)
AWS docs: “Neptune Analytics vector search”, “DynamoDB TTL”
Related sub-skills: analytics-vs-database (choosing), connectivity (setup)
Related skills: DynamoDB (short-term memory table design)

references/agentic-memory.md

Raw file

aws/agent-toolkit-for-aws