doctor

Verify that MemoGrafter, its configuration, PostgreSQL schema, pgvector, and optional recall cache are ready.

Purpose

Run Doctor after migration or whenever an environment stops behaving as expected. It performs read-only diagnostics and does not modify your configuration, database, or cache.

Doctor does not require the normal initialization gate before starting. Missing configuration is reported as a required failure while independent checks continue where possible.

Run Doctor

terminal

npx memo-grafter doctor

Checks performed

The active Node.js version and installed MemoGrafter version.

Whether MemoGrafter configuration files and DATABASE_URL are available.

PostgreSQL connectivity and the server version.

Whether pgvector is available on the PostgreSQL server and enabled in the selected database.

Whether mg_migrations exists and records the current MemoGrafter migration version.

Whether all required core MemoGrafter tables exist.

Redis reachability only when recall caching is configured through cache.connectionString.

Database resolution order

Doctor resolves the database exactly as migration does. The first available value wins:

The --db command-line option.

The project .env file or DATABASE_URL environment variable.

src/memo-grafter/mg.config.ts.

Root mg.config.ts.

Override the database

Use --db to diagnose a specific database without changing project configuration. Doctor uses the supplied connection string but never prints it in the report.

terminal

npx memo-grafter doctor --db postgres://postgres:postgres@localhost:5432/memo_grafter

Dependency-aware checks

Checks run in dependency order. If PostgreSQL cannot be reached, Doctor reports that required failure and marks pgvector, migration, and schema checks as skipped instead of producing misleading secondary failures.

passed: the check completed successfully.

failed: a required readiness check did not pass.

warning: an optional integration is unavailable or degraded.

skipped: a prerequisite was unavailable or the optional feature is not configured.

Optional Redis behavior

Redis is optional in the current Doctor implementation. PostgreSQL-backed recall remains available when an optional recall cache cannot be reached.

An unconfigured recall cache is skipped.

A reachable cache configured through cache.connectionString passes its Redis PING check.

An unreachable configured cache produces a warning, not a required failure.

REDIS_URL alone is not active recall-cache configuration and does not trigger the Redis check.

Exit codes

Doctor stores checks internally as structured passed, failed, warning, or skipped results so future output modes can reuse the same diagnostics.

0: all required checks passed.

1: one or more required checks failed.

2: invalid command usage, such as an unknown option or --db without a value.

Optional Redis warnings do not produce exit code 1.

Troubleshooting

Run Doctor from the server-side package that contains MemoGrafter.

Run npx memo-grafter migrate before diagnosing a new database.

Confirm the expected .env file and configuration files are available from the current working directory.

Use npx memo-grafter doctor --help to inspect options supported by the installed package version.