How-To Guides

Practical guides for accomplishing specific tasks with neo4j-agent-memory.

How-to guides are task-oriented. They take you through the steps required to solve a real-world problem. They assume you already know the basics and focus on building your context graph—the personalized knowledge structure that makes your agents intelligent.

Deployment & Backend

Decide how to run agent memory: hosted service or self-hosted Neo4j.

Guide What You’ll Accomplish

Use NAMS (Hosted Service)

Run agent memory with zero infrastructure. Get an API key, point MemoryClient at the hosted endpoint, and skip operating Neo4j entirely.

Migrate from Bolt to NAMS

Port an existing self-hosted deployment to the hosted service. Includes the full NotSupportedError reference for bolt-only methods.

Multi-Tenant Memory

Use user_identifier= to scope writes and reads per end-user. Required for SaaS-style deployments where one backend serves many users.

Multi-Agent Patterns

When two or more agents share a memory graph — whether across languages, frameworks, or services.

Guide What You’ll Accomplish

Cross-Agent Memory Sharing (concept)

Understand the conversation-vs-entity namespace split, how Python and TypeScript agents share the same graph, and the typical multi-agent architecture.

Scope by user_identifier

The per-user scoping primitive that keeps tenants isolated on a shared backend.

Audit Cross-Agent Reasoning

Query :TOUCHED edges to answer "which agent affected which entity, and when?" One-hop traversal across the shared graph.

Wire MCP into Multi-Agent Stacks

Expose the memory surface as MCP tools so any MCP-aware agent (Claude Desktop, Cursor, custom dispatchers) shares the same graph.

Core Context Graph Operations

Build and query your context graph—the foundation for personalized agent interactions.

Guide What You’ll Accomplish

Store and Search Messages

Add messages to conversations, search by semantic similarity, manage sessions, build conversation context.

Work with Entities

Create, update, and query entities in your context graph. Link entities to messages. Build relationship networks.

Manage User Preferences

Store and retrieve user preferences. Personalize agent responses. Learn from user behavior.

Record Reasoning Traces

Capture agent reasoning steps and tool calls. Learn from past successes. Improve agent decisions over time.

Entity Extraction & Knowledge Building

Automatically extract entities and relationships to populate your context graph from conversations and documents.

Guide What You’ll Accomplish

Adopt an Existing Domain Graph

Layer agent memory on top of a graph that already exists in production. Attach the :Entity super-label and library-managed properties idempotently with client.schema.adopt_existing_graph().

Configure Entity Extraction

Set up spaCy, GLiNER, or LLM extractors. Create custom domain schemas for financial services, ecommerce, or any industry. Build multi-stage pipelines.

Run Without an LLM

Use spaCy/GLiNER-only extraction with llm=None. Run in air-gapped environments or without an OpenAI key.

Process Documents in Batch

Extract entities from large document collections efficiently. Handle streaming for long documents. Import product catalogs or financial reports.

Handle Duplicate Entities

Configure automatic deduplication. Review and merge flagged duplicates. Maintain a clean context graph.

Enable Location Geocoding (coming soon)

Add coordinates to location entities. Query locations by proximity. Build location-aware context.

Enrich Entities with External Data (coming soon)

Add Wikipedia descriptions and images to entities automatically. Enhance your context graph with external knowledge.

Agent Framework Integrations

Connect neo4j-agent-memory to popular agent frameworks for persistent, shared context graphs.

Guide What You’ll Accomplish

Use with PydanticAI

Integrate memory as a PydanticAI dependency. Create memory-enabled tools. Build shopping assistants and financial advisors.

Use with LangChain

Implement custom chat message history. Create context graph tools. Add callbacks for reasoning traces.

Use with LlamaIndex

Build context-aware retrievers combining documents and graph knowledge. Create RAG applications with persistent memory.

Use with CrewAI

Share context graphs across multiple agents. Build collaborative multi-agent systems with persistent shared memory.

Add MCP Server to create-context-graph Projects

Connect Claude Desktop to scaffolded projects. Query domain-specific knowledge graphs through natural conversation.

TypeScript SDK (@neo4j-labs/agent-memory)

The TypeScript SDK targets the hosted NAMS service. It runs on Node 20+, Bun, Deno, Cloudflare Workers, and Vercel Edge.

Guide What You’ll Accomplish

Authenticate

API key handling, OAuth refresh, scope management for the TypeScript SDK.

Deploy to Edge Runtimes

Run agent memory on Cloudflare Workers or Vercel Edge — the fetch-only transport works everywhere.

Vercel AI SDK Middleware

Three-tier context injection + automatic persistence as a LanguageModelV1Middleware.

MCP Tools

Wire the standard 12-tool memory surface into Claude Desktop, Cursor, or any MCP-aware client.

LangChain JS

Neo4jChatMessageHistory and Neo4jEntityRetriever duck-typed against LangChain JS.

Mastra

Neo4jMastraMemory provider for the Mastra agent framework.

AWS Strands Agents (JS)

Session storage + conversation manager + reasoning hooks for the Strands JS SDK.

Observability

Request/response logging, request-id correlation, OpenTelemetry-compatible event stream.

Handle Errors

The TS exception hierarchy, retry policy, and request-id propagation.

Troubleshooting

Common failure modes and how to diagnose them.

Enterprise Use Cases

These guides include examples for common enterprise scenarios:

  • Financial Services: Client profiles, portfolio analysis, compliance tracking, advisory recommendations

  • Ecommerce Retail: Customer preferences, product recommendations, purchase history, personalized shopping

How-To Guide Philosophy

Each guide follows a consistent structure:

  1. Goal: What you’ll accomplish (one sentence)

  2. Prerequisites: What you need before starting

  3. Steps: Numbered, actionable instructions

  4. Verification: How to confirm it worked

  5. See Also: Related guides and reference material

If you’re new to neo4j-agent-memory, start with the Tutorials first.

For understanding the concepts behind these operations, see the Explanation section.

For complete API details and configuration options, see the Reference section.