CLI

CLI Reference

Tip

Value Proposition: The Memory Journal CLI empowers developers to seamlessly manage, administer, and troubleshoot their project's memory directly from the terminal, bypassing the need for an AI agent to perform routine database operations.

The Memory Journal CLI provides complete administrative control for managing and configuring your environment:

memory-journal-mcp [command] [options]

If no command is provided, it defaults to serve (starts the MCP server). Passing --help --json outputs a machine-readable JSON CLI manifest of all commands, options, arguments, and AI usage instructions. The CLI also automatically normalizes snake_case long flags (e.g., --project_number, --expected_version) to kebab-case (--project-number, --expected-version).

Option	Default	Description
--config <path>	(none)	Path to configuration file (.yaml, .yml, .json) (env: MEMORY_JOURNAL_CONFIG)
--dump-config	false	Print effective configuration and exit
--transport <type>	stdio	Transport type: stdio or http (env: TRANSPORT)
--stdio	false	Shortcut for --transport stdio
--http	false	Shortcut for --transport http
--port <number>	3000	HTTP port (for http transport) (env: PORT)
--server-host <host>	localhost	HTTP bind address (env: MCP_HOST or HOST)
--stateless	false	Use stateless HTTP mode (no session management) (env: STATELESS)
--db <path>, --database <path>	./memory_journal.db	Database path (env: DB_PATH)
--tool-filter <filter>	(none)	Tool filter string (e.g., "starter", "codemode", "core,search") (env: MEMORY_JOURNAL_MCP_TOOL_FILTER / config: toolFilter)
--default-project <number>	(none)	Default GitHub Project number (env: DEFAULT_PROJECT_NUMBER)
--embedding-model <id>	Xenova/all-MiniLM-L6-v2	HuggingFace feature extraction model for semantic search (env: EMBEDDING_MODEL)
--auto-rebuild-index	false	Rebuild vector index on server startup (env: AUTO_REBUILD_INDEX)
--log-level <level>	info	Log level: debug, info, notice, warning, error, critical (env: LOG_LEVEL)
--cors-origin <origins>	(blank)	CORS allowed origins (comma-separated, exact-match only) (env: CORS_ORIGIN or MCP_CORS_ORIGIN)
--auth-token <token>	(none)	Bearer token for HTTP authentication (env: MCP_AUTH_TOKEN)
--default-workspace-id <id>	default	Default workspace ID for isolating memory journal data (multi-tenancy) (env: DEFAULT_WORKSPACE_ID)
--codemode-max-result-size <bytes>	102400	Max Code Mode result payload in bytes (env: CODE_MODE_MAX_RESULT_SIZE)
--enable-hsts	false	Send HSTS header on HTTP responses (env: MCP_ENABLE_HSTS)
--team-db <path>, --team-database <path>	(none)	Path to team database file (enables team tools) (env: TEAM_DB_PATH)
--additional-team-dbs <json>	(none)	Additional team database mappings as JSON (env: ADDITIONAL_TEAM_DBS)
--team-default-role <role>	denied	Default role for unrecognized team authors (env: TEAM_DEFAULT_ROLE)
--team-admin <name>	(none)	Bootstrap this author as admin (headless mode) (env: TEAM_ADMIN)
--allowed-io-roots <paths>	(none)	Comma-separated absolute paths for filesystem jailing (env: ALLOWED_IO_ROOTS)
--trust-proxy	false	Trust reverse proxy headers e.g. X-Forwarded-For (env: TRUST_PROXY)
--public-origin <url>	(none)	Public origin URL for webhooks and OAuth redirects (env: PUBLIC_ORIGIN)
--oauth-enabled	false	Enable OAuth 2.1 authentication (env: OAUTH_ENABLED)
--auth-scopes <scopes>	read	Valid scopes for static Bearer token authentication (env: MCP_AUTH_SCOPES, defaults to read)
--oauth-issuer <url>	(none)	OAuth issuer URL (env: OAUTH_ISSUER)
--oauth-audience <aud>	(none)	Expected JWT audience claim (env: OAUTH_AUDIENCE)
--oauth-jwks-uri <url>	(none)	JWKS endpoint for token verification (env: OAUTH_JWKS_URI)
--oauth-clock-tolerance <s>	60	Clock skew tolerance for JWT validation (seconds) (env: OAUTH_CLOCK_TOLERANCE)
--oauth-allow-plaintext-loopback	false	Allow plaintext loopback OAuth issuer (dev only) (env: OAUTH_ALLOW_PLAINTEXT_LOOPBACK)
--backup-interval <minutes>	0	Automated backup interval, HTTP only (0 = disabled) (env: BACKUP_INTERVAL)
--keep-backups <count>	5	Max backups to retain during automated cleanup (env: KEEP_BACKUPS)
--vacuum-interval <minutes>	0	Database optimize interval, HTTP only (0 = disabled) (env: VACUUM_INTERVAL)
--rebuild-index-interval <minutes>	0	Vector index rebuild interval, HTTP only (0 = disabled) (env: REBUILD_INDEX_INTERVAL)
--digest-interval <minutes>	0	Analytics digest interval, HTTP only (0 = disabled; recommended: 1440) (env: DIGEST_INTERVAL)
--report-interval <minutes>	0	Scheduled report generation interval, HTTP only (0 = disabled) (env: REPORT_INTERVAL)
--auto-prune-interval <minutes>	0	Automated garbage collection interval, HTTP only (0 = disabled) (env: AUTO_PRUNE_INTERVAL_MINUTES)
--report-webhook-url <url>	(none)	Webhook URL for report delivery (POST) (env: REPORT_WEBHOOK_URL)
--report-webhook-auth <token>	(none)	Optional Authorization header for the report webhook (env: REPORT_WEBHOOK_AUTH)
--report-content-type <type>	slack	Webhook payload format: slack, discord, or json (env: REPORT_CONTENT_TYPE)
--briefing-importance-threshold <threshold>	0.3	Min importance score (0.0 to 1.0) for an entry to be included in briefing (env: BRIEFING_IMPORTANCE_THRESHOLD)
--briefing-entries <n>	3	Journal entries in briefing (env: BRIEFING_ENTRY_COUNT)
--briefing-commits <n>	3	Number of commits to include in the briefing context (env: BRIEFING_COMMIT_COUNT)
--briefing-summaries <n>	1	Session summaries in briefing (env: BRIEFING_SUMMARY_COUNT)
--briefing-include-team	false	Include team DB entries in briefing (env: BRIEFING_INCLUDE_TEAM)
--briefing-milestones <n>	3	Milestones to list in briefing (0 = hide) (env: BRIEFING_MILESTONE_COUNT)
--briefing-issues <n>	0	Issues to list in briefing (0 = count only) (env: BRIEFING_ISSUE_COUNT)
--briefing-prs <n>	0	PRs to list in briefing (0 = count only; alias: --briefing-pr-count <n>) (env: BRIEFING_PR_COUNT)
--briefing-pr-status	false	Show PR status breakdown (open/merged/closed) (env: BRIEFING_PR_STATUS)
--rules-file <path>	(none)	Path to user rules file for agent awareness (env: RULES_FILE_PATH)
--skills-dir <path>	(none)	Path to skills directory for agent awareness (env: SKILLS_DIR_PATH)
--workflow-summary <text>	(none)	Workflow summary for memory://workflows resource (env: MEMORY_JOURNAL_WORKFLOW_SUMMARY)
--briefing-workflows <n>	0	Workflow runs to list in briefing (0 = status only) (env: BRIEFING_WORKFLOW_COUNT)
--briefing-workflow-status	false	Show workflow status breakdown in briefing (env: BRIEFING_WORKFLOW_STATUS)
--briefing-copilot	false	Aggregate Copilot review state across PRs (env: BRIEFING_COPILOT_REVIEWS)
--archive-older-than-days <days>	0	Archive active entries older than N days with importance below threshold (env: ARCHIVE_OLDER_THAN_DAYS, 0 = disabled)
--prune-older-than-days <days>	0	Soft-delete entries older than N days with importance below threshold on startup (env: PRUNE_OLDER_THAN_DAYS, 0 = disabled)
--hard-delete-older-than-days <days>	0	Permanently delete soft-deleted entries that have been dead for N days (env: HARD_DELETE_OLDER_THAN_DAYS, 0 = disabled)
--prune-importance-threshold <n>	0.15	Importance score threshold (0.0–1.0) — entries below this are pruned (env: PRUNE_IMPORTANCE_THRESHOLD)
--prune-dry-run	false	Log auto-prune candidates without actually deleting them (env: PRUNE_DRY_RUN)
--prune-exclude-tags <tags>	(none)	Comma-separated tags to exclude from auto-prune (env: PRUNE_EXCLUDE_TAGS)
--codemode-internal-full-access	false	Bypass tool filter inside Code Mode sandbox (all groups accessible via mj.*) (env: CODEMODE_INTERNAL_FULL_ACCESS)
--audit-log <path>	(none)	JSONL audit log path, or stderr for containers (env: AUDIT_LOG_PATH)
--no-audit-redact	redact=true	Disable redaction of tool arguments in audit entries (env: AUDIT_REDACT=false)
--audit-reads	false	Log read-scoped tool calls in addition to write/admin (env: AUDIT_READS)
--audit-log-max-size <bytes>	10485760	Max audit log file size in bytes before rotation (env: AUDIT_LOG_MAX_SIZE)
--no-agent-healing	healing=true	Disable autonomous MCP tool and parameter healing/interception (env: MCP_AGENT_HEALING=false)
--max-tool-input-elements <count>	25000	Maximum number of array/object elements allowed in tool input arguments (0 = disabled, env: MAX_TOOL_INPUT_ELEMENTS)
--metrics-export <format>	(none)	Metrics export format (e.g. prometheus) (env: METRICS_EXPORT)
--metrics-port <port>	9465 (when --metrics-export prometheus is active; host via MJ_METRICS_HOST, default 127.0.0.1)	Dedicated port for exposing Prometheus /metrics endpoint (env: MJ_METRICS_PORT)
--persist-metrics	false	Persist metrics to disk across server restarts (env: PERSIST_METRICS)
--metrics-path <path>	(none)	Custom path to the metrics JSON file (env: METRICS_PATH)
--json	false	Format output as JSON (for specific commands)

Transport Examples

stdio (default - for MCP clients):

memory-journal-mcp

HTTP stateful (for web clients):

memory-journal-mcp --transport http --port 3000 --allowed-io-roots /path/to/allowed/dir

HTTP stateful (bind to all interfaces — required for Docker, set by default in Dockerfile):

memory-journal-mcp --transport http --port 3000 --server-host 0.0.0.0 --allowed-io-roots /path/to/allowed/dir --auth-token <token>

HTTP stateless (for serverless):

memory-journal-mcp --transport http --port 3000 --stateless --allowed-io-roots /path/to/allowed/dir

---

Subcommands

In addition to starting the server, the CLI provides several subcommands for local administration and scripting. Agent-optimized CLI commands include search, visualize, analytics, io, and admin.

Note

Shared Subcommand Options & Output Streams: Database-backed subcommands (exec, admin, search, session, analytics, io, entry) inherit the Core, Database, and --json option groups (--db / --database <path>, --team-db / --team-database <path>, --additional-team-dbs <paths>, --team-default-role <role>, --team-admin <author>, --config <path>, --dump-config, --log-level <level>, --max-tool-input-elements <n>, and --no-agent-healing; exec also inherits the Workspace, Vector, Code Mode, and Audit option groups, while visualize inherits Core and Database options without --json). For project, project create inherits Core, Database, and --json, project list supports --json, and project update / project delete take only their subcommand-specific flags. In addition, human-readable mutation confirmations across admin (backup, restore, vacuum, prune), entry (create, update), and visualize --out emit to stderr so stdout stays pipe-safe for --json (all io subcommands output JSON directly to stdout).

Tip

Native File Flags for JSON: All CLI subcommands that accept JSON strings (like --rel or --auto-context) also provide native file flags (e.g., --rel-file, --auto-context-file, --metadata). This eliminates shell quoting friction when agents execute commands.

Exec

Execute a Code Mode JavaScript file locally without starting a server. This reads the JavaScript file at <file> and executes it in the isolated Code Mode VM sandbox via mj_execute_code against the local SQLite journal (forcing codemodeEnabled: true and bypassing test database path overrides).

memory-journal-mcp exec <file> [options]

Admin

Database administration utilities. These are powerful commands, so verify the target database before executing. All admin subcommands also accept --db <path>, --config <path>, and --json.

# Export the database to a timestamped backup file (optionally specify --dest <path>)
memory-journal-mcp admin backup [--dest <path>] [--db <path>] [--config <path>] [--json]

# Restore the database from a backup file (Overwrites the current DB!)
memory-journal-mcp admin restore <file> [--db <path>] [--config <path>] [--json]

# Optimize database query planner and flush WAL
memory-journal-mcp admin vacuum [--db <path>] [--config <path>] [--json]

# Run autonomous database pruning
memory-journal-mcp admin prune [--dry-run] [--prune-dry-run] [--exclude-tags <tags>] [--prune-exclude-tags <tags>] [--archive-older-than-days <days>] [--prune-older-than-days <days>] [--hard-delete-older-than-days <days>] [--prune-importance-threshold <n>] [--auto-prune-interval <minutes>] [--db <path>] [--config <path>] [--json]

# Search operational telemetry audit logs (reads --audit-log <path>, AUDIT_LOG_PATH, or MEMORY_JOURNAL_AUDIT_LOG; --limit defaults to 100 and output is always JSON)
memory-journal-mcp admin audit [--audit-log <path>] [--no-audit-redact] [--audit-reads] [--audit-log-max-size <bytes>] [--limit <number>] [--tool <string>] [--user <string>] [--category <string>] [--status <success|error>] [--db <path>] [--config <path>] [--json]

# Rebuild semantic search vector index (always outputs JSON)
memory-journal-mcp admin rebuild-index [--team] [--db <path>] [--config <path>] [--json]

Search

Search journal entries, returning results in JSON format optimized for agents. Pass the search query positionally (<query>) or via -q / --query <string> (aliases: --term <string>, --keyword <string>), and --limit defaults to 50. In the CLI, --mode auto (default) runs FTS5 search with fuzzy matching and typo auto-correction enabled, --mode fts (and --mode hybrid) runs exact FTS5 search, and --mode semantic runs vector similarity search.

memory-journal-mcp search [query] [-q|--query|--term|--keyword <string>] [--mode <auto|fts|semantic|hybrid>] [--limit <number>] [--team] [--db <path>] [--config <path>] [--json]

Session

Search or list journal entries associated with sessions, returning results in JSON format optimized for agents. By default it searches for "session summary", or searches for "session <args...>" when positional arguments are supplied.

memory-journal-mcp session [args...] [--mode <mode>] [--limit <number>] [--team] [--db <path>] [--config <path>] [--json]

IO

Import and export database entries. All io subcommands emit JSON results to stdout, and --dir <path> is required for io export-markdown, io import-markdown, and io import-external.

# Export database entries to a JSON file
memory-journal-mcp io export-json [--dest <path>] [--db <path>] [--config <path>] [--json]

# Export entries to a directory of markdown files (--dir <path> is required)
memory-journal-mcp io export-markdown --dir <path> [--db <path>] [--config <path>] [--json]

# Import entries from a directory of markdown files
memory-journal-mcp io import-markdown --dir <path> [--db <path>] [--config <path>] [--json]

# Import entries from external knowledge bases (Notion/Obsidian/Logseq)
memory-journal-mcp io import-external --dir <path> --format <notion|obsidian|logseq> [--db <path>] [--config <path>] [--json]

Visualize

Generate a Mermaid relationship graph from journal entries.

memory-journal-mcp visualize [--out <path>] [--team] [--db <path>] [--config <path>]

Analytics

Database analytics and cross-project insights. Both analytics stats and analytics insights always emit formatted JSON output to stdout.

# Get basic database statistics (always emits formatted JSON to stdout)
memory-journal-mcp analytics stats [--team] [--db <path>] [--config <path>] [--json]

# Get cross-project insights (always emits formatted JSON to stdout)
memory-journal-mcp analytics insights [--team] [--db <path>] [--config <path>] [--json]

Project

Manage projects in the memory-journal-mcp global registry. Note that project create registers --config <path> directly and defaults --number to 0 for the initialization entry when omitted, whereas project list, project update, and project delete resolve custom config paths via the MEMORY_JOURNAL_CONFIG environment variable. Among the project subcommands, --json formats project list as JSON while project create, project update, and project delete always emit human-readable status messages.

# Register a new project in the global registry (defaults --number to 0 for the init entry when omitted)
memory-journal-mcp project create <name> --path <absolute_path> [--number <github_project_number>] [--db <path>] [--team-db <path>] [--config <path>] [--log-level <level>] [--dump-config] [--skip-init] [--json]

# Update an existing project in the registry (custom config path via MEMORY_JOURNAL_CONFIG)
memory-journal-mcp project update <name> [--path <absolute_path>] [--number <github_project_number>] [--rename <new_name>]

# Remove a project from the registry (`delete` or `remove`; custom config path via MEMORY_JOURNAL_CONFIG)
memory-journal-mcp project delete <name>
memory-journal-mcp project remove <name>

# List all registered projects (supports [--json]; custom config path via MEMORY_JOURNAL_CONFIG)
memory-journal-mcp project list [--json]

Entry

Manage journal entries directly from the command line without needing an MCP client connection. Content can be supplied via --file / --content-file, -c / --content, positional [content...], stdin piping, or interactive TTY mode when invoked in a terminal without content flags.

# Create a new journal entry (positional [args...] are joined as inline content)
memory-journal-mcp entry create [args...] [-f|--file|--content-file <markdown_file>] [--metadata <json_file>] [--json]

# Update an existing journal entry (--expected-version is required for optimistic concurrency control)
memory-journal-mcp entry update --id <number> --expected-version <number> [content] [-f|--file|--content-file <markdown_file>] [--metadata <json_file>] [--json]

Note

Metadata Precedence (CLI flags > --metadata > YAML frontmatter): The entry create and entry update commands support parsing YAML frontmatter embedded in the markdown file (-f / --file / --content-file) as well as JSON metadata via --metadata <path>. Explicit CLI flags take highest priority, overriding --metadata <path>, which in turn overrides YAML frontmatter (CLI flags > --metadata > YAML frontmatter, except relationships where frontmatter and --metadata are merged into metadata first and checked before --rel-file / --rel, resulting in --metadata > YAML frontmatter > --rel-file > --rel).

Common Entry Flags:

• -f, --file, --content-file <path>: Load markdown content from a file (recommended over -c for long content)
• -c, --content <string> (aliases: --body, and -d, --description on entry update only): Raw markdown content string (or pass positional [args...] on create / [content] on update / pipe via stdin)
• --expected-version <number>: (Required for update) Expected entry version for optimistic concurrency control
• --title <title> (aliases: -s, --summary on entry create only): Prepend an H1 to content
• -t, --type <type> (alias: --category): Entry type
• --tags <tags> (alias: --tag): Comma-separated tags
• -p, --project, --project-number <number>: Project number (entry create; on entry update, pass "project_number" via --metadata JSON or YAML frontmatter)
• -w, --workspace, --workspace-id, --workspace_id <id>: Workspace ID (entry create)
• --session, --session-id <id>: Session ID
• --trust, --trust-score <number> (alias: --confidence on entry create only): Trust score (0.0 to 1.0)
• --impact, --impact-score <number>: Impact score (0.0 to 1.0)
• --validation-status <status> (alias: --validation): Validation status (passed|none|failed)
• --related-to <ids>: Comma-separated entry IDs to relate to
• --rel, --relationships <json>: JSON string of relationships
• --auto-context <json>: JSON string for auto context
• --metadata <path>: Load unified metadata JSON from a file (overrides YAML frontmatter; explicit CLI flags take precedence over --metadata, except relationships where --metadata > YAML frontmatter > --rel-file > --rel)
• --rel-file <path>: Load relationships JSON from a file
• --auto-context-file <path>: Load auto context JSON from a file
• --team: Route to team database
• --json: Format output as structured JSON