Development setup
Prepare a local MemoGrafter checkout with PostgreSQL, optional Redis, migrations, tests, and Studio.
Requirements
package-lock.json, so use npm for dependency changes.Fork and clone
Fork mayhemking007/memo-grafter on GitHub, clone your fork, and add the main repository as the upstream remote.
git clone https://github.com/<your-github-username>/memo-grafter.git
cd memo-grafter
git remote add upstream https://github.com/mayhemking007/memo-grafter.git
git remote -vInstall dependencies
npm installConfigure the environment
Copy the example environment file. Its default DATABASE_URL matches the PostgreSQL service in the repository's compose.yml.
If you use an existing database, replace the default URL. Leave REDIS_URL empty unless you are enabling queue mode or the recall cache; the environment variable alone does not activate either feature.
cp .env.example .envCopy-Item .env.example .envStart PostgreSQL only
PostgreSQL with pgvector is sufficient for normal development and the default unit tests. Start only the postgres service when you are not working on Redis-backed features.
docker compose up -d postgresStart PostgreSQL and Redis
Start the complete contributor stack when testing queue mode, recall caching, or Redis integrations.
docker compose up -dInspect local services
Run the Redis command only when Redis is running; a healthy Redis service returns PONG.
docker compose ps
docker compose logs -f postgres
docker compose exec postgres pg_isready -U memografter -d memografter
docker compose exec postgres psql -U memografter -d memografter -c "SELECT extname FROM pg_extension WHERE extname IN ('vector', 'pgcrypto') ORDER BY extname;"
docker compose exec redis redis-cli pingBuild, initialize, and migrate
Initialization creates the project-local MemoGrafter configuration and schema reference. Migration enables vector and pgcrypto and creates or updates MemoGrafter-owned mg_* tables. It is safe to run again.
npm run build
npx memo-grafter init
npx memo-grafter migrate
npx memo-grafter doctorRun the standard checks
npm run typecheck
npm run lint
npm run test:runStart Studio
Start the local Studio after migration to inspect sessions, graphs, tables, and Prompt Preview. Studio is local development tooling and should not be exposed as a public application endpoint.
npx memo-grafter studioProvider setup smoke tests
Provider smoke tests require a working DATABASE_URL and the matching provider API key. They call external APIs and may incur normal usage charges. Redis is not required.
# Requires OPENAI_API_KEY
npx tsx --env-file=.env tests/manual/setup-test/openai-smoke.ts
# Requires ANTHROPIC_API_KEY
npx tsx --env-file=.env tests/manual/setup-test/anthropic-smoke.ts
# Requires GEMINI_API_KEY
npx tsx --env-file=.env tests/manual/setup-test/gemini-smoke.tsReset local services
Stop the containers without removing local database or Redis data with docker compose down.
This permanently deletes local development data
Running docker compose down -v removes the PostgreSQL and Redis volumes. Back up anything you need before using it.
docker compose down
# Permanently remove local PostgreSQL and Redis data
docker compose down -vCommon setup failures
5432 or 6379 already in use: stop the conflicting service or adjust the Compose mapping and matching environment URL.docker compose ps and docker compose logs postgres..env or DATABASE_URL mismatch: copy .env.example and make the credentials, database, host, and port match the active PostgreSQL service.compose.yml changes.npx memo-grafter init, npx memo-grafter migrate, and npx memo-grafter doctor.pgcrypto unavailable: use the repository Compose service or install and enable the extensions on the selected PostgreSQL server.