CLI Reference

Command-line interface for neo4j-agent-memory extraction and schema management.

Installation

Install with CLI extras:

pip install neo4j-agent-memory[cli]

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

--file, -f

none

Read text from file instead

--extractor, -e

gliner

Extractor to use: gliner, spacy, llm, hybrid

--entity-types, -t

all

Entity types to extract (can repeat)

--format

table

Output format: table, json, jsonl

--threshold

0.5

Confidence threshold (0.0-1.0)

--schema

poleo

Domain schema: poleo, podcast, news, etc.

--verbose, -v

false

Show extraction details

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 -t Person -t Organization "..."

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

# Use domain schema
neo4j-agent-memory extract --schema podcast "..."

Output Formats

Table (default):

┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Entity         ┃ Type         ┃ Subtype     ┃ Confidence  ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ John Smith     │ PERSON       │ INDIVIDUAL  │ 0.95        │
│ Acme Corp      │ ORGANIZATION │ COMPANY     │ 0.92        │
│ New York       │ LOCATION     │ CITY        │ 0.88        │
└────────────────┴──────────────┴─────────────┴─────────────┘

JSON:

{
  "entities": [
    {"name": "John Smith", "type": "PERSON", "subtype": "INDIVIDUAL", "confidence": 0.95},
    {"name": "Acme Corp", "type": "ORGANIZATION", "subtype": "COMPANY", "confidence": 0.92}
  ],
  "metadata": {
    "extractor": "gliner",
    "schema": "poleo",
    "duration_ms": 234
  }
}

JSON Lines:

{"name": "John Smith", "type": "PERSON", "subtype": "INDIVIDUAL", "confidence": 0.95}
{"name": "Acme Corp", "type": "ORGANIZATION", "subtype": "COMPANY", "confidence": 0.92}

schemas

Manage entity extraction schemas stored in Neo4j.

schemas list

List all schemas in the database.

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

--uri

bolt://localhost:7687

Neo4j connection URI

--username

neo4j

Neo4j username

--password

required

Neo4j password

--format

table

Output format: table, json

schemas show

Show details of a specific schema.

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

--version

latest

Specific version to show

--format

yaml

Output format: yaml, json

schemas validate

Validate a schema file.

neo4j-agent-memory schemas validate SCHEMA_FILE

Examples

# List schemas
neo4j-agent-memory schemas list --password $NEO4J_PASSWORD

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

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

stats

Show memory statistics from Neo4j.

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

--uri

bolt://localhost:7687

Neo4j connection URI

--username

neo4j

Neo4j username

--password

required

Neo4j password

--format

table

Output format: table, json

Example

neo4j-agent-memory stats --password $NEO4J_PASSWORD

Output:

Memory Statistics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Short-Term Memory
  Conversations: 42
  Messages: 1,234

Long-Term Memory
  Entities: 567
    PERSON: 234
    ORGANIZATION: 123
    LOCATION: 89
    OBJECT: 45
    EVENT: 76
  Preferences: 23
  Facts: 156

Reasoning Memory
  Traces: 89
  Steps: 445
  Tool Calls: 312

mcp serve

Start the MCP server for Claude Desktop and other MCP hosts.

neo4j-agent-memory mcp serve [OPTIONS]

Options

Option Default Description

--uri

bolt://localhost:7687

Neo4j connection URI (env: NEO4J_URI).

--user

neo4j

Neo4j username (env: NEO4J_USER).

--password

required

Neo4j password (env: NEO4J_PASSWORD).

--database

neo4j

Neo4j database name (env: NEO4J_DATABASE).

--transport

stdio

MCP transport (stdio, sse, or http).

--host

127.0.0.1

Host for network transports.

--port

8080

Port for network transports.

--profile

extended

Tool profile: core (6 tools) or extended (16 tools).

--session-strategy

per_conversation

per_conversation, per_day, or persistent.

--user-id

none

User ID for per_day/persistent strategies (env: MCP_USER_ID).

--observation-threshold

30000

Token threshold for observational memory compression.

--no-auto-preferences

disabled

Disable automatic preference detection.

--llm

none

LLM provider string, e.g. anthropic/claude-3-5-sonnet-latest (env: NAM_LLM). See Bring Your Own Model.

--llm-api-key

none

API key override for the LLM provider (env: NAM_LLM_API_KEY).

--llm-api-base

none

Base URL override (vLLM, Ollama, internal endpoint).

--embedding

none

Embedding provider string, e.g. BAAI/bge-small-en-v1.5 (env: NAM_EMBEDDING).

--embedding-dimensions

none

Override embedding dimensions for unknown models.

Examples

# Default (OpenAI embeddings, OpenAI gpt-4o-mini extractor).
neo4j-agent-memory mcp serve --password mypw

# Anthropic + local sentence-transformers, no OpenAI dependency.
neo4j-agent-memory mcp serve \
  --password mypw \
  --llm anthropic/claude-3-5-sonnet-latest \
  --embedding BAAI/bge-small-en-v1.5

# Local vLLM endpoint via LiteLLM.
neo4j-agent-memory mcp serve \
  --password mypw \
  --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 \
  --password mypw \
  --profile core \
  --session-strategy per_day \
  --user-id alice

Environment Variables

The CLI respects these environment variables:

# Neo4j connection (avoids passing --password)
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=password

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

# v0.3+ 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