CLI reference

Command-line interface for local extraction, bolt schema/statistics commands, and MCP serving with bolt or NAMS. Add the selected extractor/provider extras and model files before inference; the CLI extra supplies command rendering, not every model.

Installation

Install the cli extra and PyYAML. The cli extra does not include PyYAML, but the CLI needs it to read YAML schema files (extract --schema, schemas validate) and for the default YAML output of schemas show:

pip install 'neo4j-agent-memory[cli]==0.7.0' pyyaml

Add the extras for the commands you run:

Command Extras to add

extract (default --extractor gliner)

gliner2. The GLiNER2.5 checkpoint downloads on first use.

extract --extractor llm

openai, with OPENAI_API_KEY set.

extract --extractor hybrid

gliner2 and openai.

mcp serve

mcp. On bolt, also add the provider extras your --llm and --embedding strings need; without those flags the server uses the default OpenAI embedder, so add openai and set OPENAI_API_KEY. On NAMS, add the nams extra instead; no provider extras are needed.

ontology compile

gliner2.

schemas, stats, ontology validate

None.

For example, to run every extract example on this page:

pip install 'neo4j-agent-memory[cli,gliner2,openai]==0.7.0' pyyaml

To run the MCP server against NAMS:

pip install 'neo4j-agent-memory[cli,mcp,nams]==0.7.0' pyyaml

Commands

extract

Extract entities from text or files.

neo4j-agent-memory extract [OPTIONS] [TEXT]

Arguments

Argument Description

TEXT

Text to extract entities from. Use - for stdin.

Options

Option Default Description

-f, --file

unset

Read text from a file instead of argument.

--format, -o

table

Output format (default: table). Choices: table, json, jsonl.

--schema

unset

Path to an EntitySchemaConfig YAML file.

--ontology

unset

Path to an ontology document (JSON or YAML) to extract against.

--gliner-schema

unset

Built-in domain schema for the GLiNER2.5 extractor. Choices: poleo, podcast, news, scientific, business, entertainment, medical, legal.

--entity-types, -e

unset

Entity types to extract (can be specified multiple times).

--extractor

gliner

Extractor to use (default: gliner, i.e. GLiNER2.5). Choices: gliner, llm, hybrid.

--model

unset

Model name for the GLiNER2.5 or LLM extractor (GLiNER2.5 default: fastino/gliner2.5-base-v1). With hybrid, it sets the LLM model.

--relations, --no-relations

true

Extract relations between entities.

--preferences, --no-preferences

false

Extract preferences/sentiments (LLM extractor only).

--confidence-threshold

0.5

Minimum confidence threshold (default: 0.5). Valid range: 0–1. Sets the GLiNER2.5 entity threshold; with hybrid it also filters the merged result. Not applied to --extractor llm output.

--quiet, -q

false

Suppress progress output.

--ontology, --schema, and --entity-types are alternatives for the same slot and are consulted in that order. --gliner-schema applies only with --extractor gliner, where it replaces any of the three.

Examples

# Extract from text
neo4j-agent-memory extract "John Smith works at Acme Corp in New York"

# Extract from file
neo4j-agent-memory extract --file document.txt

# Pipe from stdin
echo "Sarah lives in London" | neo4j-agent-memory extract -

# Use specific extractor
neo4j-agent-memory extract --extractor llm "..."

# Filter entity types
neo4j-agent-memory extract -e PERSON -e ORGANIZATION "..."

# JSON output
neo4j-agent-memory extract --format json "..."

# Use a YAML schema file (see the schema example below)
neo4j-agent-memory extract --schema custom_schema.yaml "..."

# Use a built-in domain schema
neo4j-agent-memory extract --gliner-schema podcast "..."

# Use your own ontology (entity labels and typed relationships)
neo4j-agent-memory extract --ontology my-ontology.yaml "..."

# Entities only, on the small checkpoint
neo4j-agent-memory extract --model fastino/gliner2.5-small-v1 --no-relations "..."

Schema input and extractor capabilities

--schema requires an existing EntitySchemaConfig YAML file, not a built-in schema name; pass a built-in name with --gliner-schema and an OntologyDocument with --ontology. For example, save this as custom_schema.yaml and run schemas validate custom_schema.yaml before extraction:

name: custom_example
version: "1.0"
entity_types:
  - name: PERSON
    description: A named person
  - name: ORGANIZATION
    description: A company or organization

The CLI converts the schema to an ontology for ExtractorBuilder: its entity types and subtypes become GLiNER2.5 labels, its relation types between declared entity types become typed relationships, and the type names become the LLM extractor’s type list. --entity-types builds an EntitySchemaConfig from bare names the same way. An EntitySchemaConfig that omits relation_types carries the POLE+O relation types by default; set relation_types: [] for entities only. GLiNER2.5 decodes relations in the same pass as entities, but only for relationship types the ontology declares. Of the built-in templates, poleo, podcast, and news declare relationships; the others are entity-only. --preferences needs --extractor llm or hybrid. --confidence-threshold sets the GLiNER2.5 entity threshold and, for hybrid, filters the merged result; it does not post-filter --extractor llm output.

Output formats

The table renders entity columns Type, Name, Confidence, and Attributes, plus relation/preference tables when present. Exact model results and confidence scores vary; GLiNER2.5 entities carry the decoded label in attributes (for example {"gliner2_label": "person"}).

The JSON serializer returns entities, relations, preferences, and source_text. Example shape:

{
  "entities": [
    {"type": "PERSON", "name": "John Smith", "confidence": 0.95, "attributes": {}}
  ],
  "relations": [],
  "preferences": [],
  "source_text": "John Smith"
}

There is no CLI metadata envelope or entity subtype field in this serializer. JSON Lines wraps each item with a kind and data:

{"type": "entity", "data": {"type": "PERSON", "name": "John Smith", "confidence": 0.95, "attributes": {}}}

Relation/preference lines use type: "relation" / type: "preference" with their corresponding data fields.

schemas

Manage EntitySchemaConfig documents stored in Neo4j (bolt only). These commands do not list the built-in domain schemas or stored ontologies; manage ontologies with client.ontology and check ontology files with ontology. Configure the Aura environment variables in Environment variables before running the connection examples.

schemas list

List all schemas in the database.

neo4j-agent-memory schemas list [OPTIONS]
Option Default Description

--format, -o

table

Output format. Choices: table, json.

--uri

bolt://localhost:7687

Neo4j URI (default: bolt://localhost:7687 or NEO4J_URI env var). Environment: NEO4J_URI.

--user

neo4j

Neo4j username (default: neo4j or NEO4J_USER env var). Environment: NEO4J_USER.

--password

unset

Neo4j password (or NEO4J_PASSWORD env var). Environment: NEO4J_PASSWORD.

schemas show

Show details of a specific schema.

neo4j-agent-memory schemas show SCHEMA_NAME [OPTIONS]
Option Default Description

--version, -v

unset

Schema version (default: active version).

--format, -o

yaml

Output format. Choices: yaml, json.

--uri

bolt://localhost:7687

Neo4j URI. Environment: NEO4J_URI.

--user

neo4j

Neo4j username. Environment: NEO4J_USER.

--password

unset

Neo4j password. Environment: NEO4J_PASSWORD.

schemas validate

Validate a schema file.

neo4j-agent-memory schemas validate SCHEMA_FILE

Examples

# List schemas
neo4j-agent-memory schemas list --uri "$NEO4J_URI" --user "$NEO4J_USERNAME"

# Show schema details
neo4j-agent-memory schemas show medical --format yaml

# Validate schema file
neo4j-agent-memory schemas validate custom_schema.yaml

ontology

Validate and compile ontology documents locally; neither command connects to Neo4j. Ontology management (create, update, activate, diff) is on the Python API through client.ontology; see Ontology API.

ontology validate

neo4j-agent-memory ontology validate FILE

Loads FILE (.json/.yaml) through load_ontology, so an EntitySchemaConfig file is accepted and converted, then reports every problem OntologyDocument.validate_structure() finds, such as duplicate labels, relationship endpoints that name no declared label, bad inverse pairs, and pole_type values outside POLE+O. Exits 1 on any problem. Output for a valid document, here the built-in POLE+O ontology:

✓ Ontology 'poleo' is valid.
  Entity types: Person, Organization, Location, Event, Object
  Relationship types: KNOWS, ALIAS_OF, MEMBER_OF, EMPLOYED_BY, ...
  Relationship patterns: 69

ontology compile

neo4j-agent-memory ontology compile FILE

Compiles the ontology into the GLiNER2.5 JointIE schema and prints it as JSON, showing the entity labels and typed relationships the model will decode against. Requires the gliner2 extra; without it the command exits 1 with an install hint.

Examples

# Check an ontology before loading it
neo4j-agent-memory ontology validate ontology.yaml

# See what the model will decode
neo4j-agent-memory ontology compile ontology.yaml

stats

Show entity extraction/provenance and extractor statistics from Neo4j (bolt only). This command is distinct from MemoryClient.get_stats().

neo4j-agent-memory stats [OPTIONS]
Option Default Description

--format, -o

table

Output format. Choices: table, json.

--uri

bolt://localhost:7687

Neo4j URI. Environment: NEO4J_URI.

--user

neo4j

Neo4j username. Environment: NEO4J_USER.

--password

unset

Neo4j password. Environment: NEO4J_PASSWORD.

Example

neo4j-agent-memory stats --uri "$NEO4J_URI" --user "$NEO4J_USERNAME"

The table contains an Extraction Statistics panel, an entity-type breakdown, and extractor counts. --format json returns an object with extraction_stats and extractor_stats; it does not return conversation/message/reasoning totals.

mcp serve

Start the MCP server for Claude Desktop and other MCP hosts. Install the mcp extra, plus nams for the hosted backend. Bolt requires a Neo4j password; NAMS requires an API key. --backend pins selection; otherwise a supplied key selects NAMS. Local provider/extraction options do not configure the hosted pipeline.

neo4j-agent-memory mcp serve [OPTIONS]

The runnable Bolt commands below use the Aura environment in Environment variables; set its URI and credentials first.

Options

Option Default Description

--uri

bolt://localhost:7687

Neo4j connection URI. Environment: NEO4J_URI.

--user

neo4j

Neo4j username. Environment: NEO4J_USER.

--password

unset

Neo4j password (or NEO4J_PASSWORD env var). Environment: NEO4J_PASSWORD.

--database

neo4j

Neo4j database name. Environment: NEO4J_DATABASE.

--transport

stdio

MCP transport (default: stdio). 'http' is Streamable HTTP; 'streamable-http' is a synonym. 'sse' is deprecated and serves Streamable HTTP with a warning. Choices: stdio, http, streamable-http, sse.

--host

127.0.0.1

Host to bind for --transport http (use 0.0.0.0 to expose it).

--port

8080

Port to bind for --transport http. The MCP endpoint is /mcp.

--profile

extended

Tool profile: core (6 tools) or extended (16 tools on bolt, 20 on NAMS). Choices: core, extended.

--session-strategy

per_conversation

Session identity strategy. Choices: per_conversation, per_day, persistent.

--user-id

unset

User ID for per_day/persistent session strategies. Environment: MCP_USER_ID.

--observation-threshold

30000

Token threshold for observational memory compression.

--no-auto-preferences

false

Disable automatic preference detection.

--llm

unset

LLM provider string (e.g. 'openai/gpt-4o-mini', 'anthropic/claude-3-5-sonnet-latest', 'ollama/llama3.2'). Resolved via neo4j_agent_memory.llm.from_provider. Environment: NAM_LLM.

--llm-api-key

unset

API key for the LLM provider (overrides provider-default env var). Environment: NAM_LLM_API_KEY.

--llm-api-base

unset

Base URL for the LLM provider (e.g. for vLLM, Ollama, or an internal endpoint). Passed through to the adapter constructor.

--embedding

unset

Embedding provider string (e.g. 'openai/text-embedding-3-small', 'BAAI/bge-small-en-v1.5'). Resolved via from_provider. Environment: NAM_EMBEDDING.

--embedding-dimensions

unset

Embedding dimensions override (for models not in the defaults table).

--backend

unset

Storage backend. 'bolt' uses direct Neo4j; 'nams' uses the hosted Neo4j Agent Memory Service REST API. Defaults to NAMS if MEMORY_API_KEY is set, otherwise bolt. Choices: bolt, nams. Environment: NAM_BACKEND.

--api-key

unset

NAMS API key (or set MEMORY_API_KEY env var). Required when --backend=nams. Environment: MEMORY_API_KEY.

--endpoint

unset

NAMS endpoint base URL. Defaults to MEMORY_ENDPOINT env var, or https://memory.neo4jlabs.com/v1 when neither is set. Environment: MEMORY_ENDPOINT.

Examples

# Bolt example (requires the corresponding provider dependencies/credentials).
neo4j-agent-memory mcp serve --backend bolt --uri "$NEO4J_URI" --user "$NEO4J_USERNAME"

# Anthropic + local sentence-transformers, no OpenAI dependency.
neo4j-agent-memory mcp serve --backend bolt \
  --uri "$NEO4J_URI" --user "$NEO4J_USERNAME" \
  --llm anthropic/claude-3-5-sonnet-latest \
  --embedding BAAI/bge-small-en-v1.5

# Local vLLM endpoint via LiteLLM.
neo4j-agent-memory mcp serve --backend bolt \
  --uri "$NEO4J_URI" --user "$NEO4J_USERNAME" \
  --llm openai/llama-3.3-70b-instruct \
  --llm-api-base https://llms.internal.corp/v1

# Core profile (fewer tools), per-day session strategy.
neo4j-agent-memory mcp serve --backend bolt \
  --uri "$NEO4J_URI" --user "$NEO4J_USERNAME" \
  --profile core \
  --session-strategy per_day \
  --user-id alice

# Streamable HTTP, for a networked deployment (Cloud Run, Kubernetes).
# The MCP endpoint is POST/GET http://<host>:8080/mcp
neo4j-agent-memory mcp serve --backend bolt \
  --uri "$NEO4J_URI" --user "$NEO4J_USERNAME" \
  --transport http \
  --host 0.0.0.0 \
  --port 8080
# Hosted MCP server; set MEMORY_API_KEY in the process environment first.
neo4j-agent-memory mcp serve --backend nams --transport stdio
--transport sse is deprecated. The MCP specification replaced the legacy HTTP+SSE transport with Streamable HTTP; the flag still starts a server but logs a warning and serves Streamable HTTP at /mcp. See Transports.

Environment variables

Copy Aura connection values from the Aura connection setup before running the Bolt examples. The examples override the local defaults listed in the option tables.

Options use their listed environment aliases. The CLI does not load .neo4j-memory.yaml or implement a NAM_CLI__…​ settings group. Example process environment:

# Neo4j connection (avoids passing --password)
export NEO4J_URI="neo4j+s://<instance-id>.databases.neo4j.io"
export NEO4J_USERNAME="neo4j"
export NEO4J_PASSWORD="replace-with-your-Aura-password"
export NEO4J_DATABASE="neo4j"
# The CLI uses NEO4J_USER, so map the exported Aura username.
export NEO4J_USER="$NEO4J_USERNAME"

# OpenAI (for LLM extractor or OpenAI provider strings)
export OPENAI_API_KEY=sk-...

# provider configuration
export NAM_LLM=anthropic/claude-3-5-sonnet-latest
export NAM_LLM_API_KEY=$ANTHROPIC_API_KEY
export NAM_EMBEDDING=BAAI/bge-small-en-v1.5

See also