Configuration

Zero-config mode

No config file needed. Run graphmemory serve in your project directory — the current directory becomes the project with sensible defaults.

Config file

For multi-project setups, custom models, auth, or workspaces — create graph-memory.yaml:

projects:
  my-app:
    projectDir: "/path/to/my-app"

Only projects.<id>.projectDir is required. Everything else has sensible defaults.

Full reference

# Default author for notes/tasks/skills
author:
  name: "Your Name"
  email: "[email protected]"

# Users (for authentication)
users:
  alice:
    name: "Alice"
    email: "[email protected]"
    apiKey: "mgm-key-abc123"
    passwordHash: "$scrypt$..."    # generated by CLI

# Server settings
server:
  host: "127.0.0.1"
  port: 3000
  defaultAccess: "rw"             # deny | r | rw
  jwtSecret: "your-secret"        # required when users are defined
  cookieSecure: true               # explicit Secure flag for cookies (default: auto)
  corsOrigins: ["http://localhost:5173"]
  accessTokenTtl: "15m"
  refreshTokenTtl: "7d"
  modelsDir: "~/.graph-memory/models"
  model:
    name: "Xenova/bge-m3"
    dtype: "q8"                   # fp32, fp16, q8, q4
  rateLimit:
    global: 600                   # requests/min
    search: 120
    auth: 10
  redis:
    enabled: true                  # must be true to activate Redis
    url: "redis://localhost:6379"  # Redis connection URL

# Projects
projects:
  my-app:
    projectDir: "/path/to/my-app"
    graphs:
      docs:
        enabled: true
        include: "**/*.md"
      code:
        enabled: true
        include: "**/*.{js,ts,jsx,tsx,mjs,mts,cjs,cts}"
      knowledge:
        enabled: true
        readonly: false           # set true to block mutations
      tasks:
        enabled: true
      files:
        enabled: true
      skills:
        enabled: true

# Workspaces (optional)
workspaces:
  backend:
    projects: [api-gateway, catalog-service]
    graphMemory: "./.workspace-backend"

Server settings

Field	Default	Description
host	127.0.0.1	Bind address
port	3000	Port
defaultAccess	rw	Default access: deny, r, rw
jwtSecret	—	Required when users are defined
cookieSecure	auto	Set cookie Secure flag. Defaults to true unless NODE_ENV=development
modelsDir	~/.graph-memory/models	Model cache directory
sessionTimeout	3600	MCP session timeout (seconds)
corsOrigins	* (all)	Allowed CORS origins
accessTokenTtl	15m	JWT access token lifetime
refreshTokenTtl	7d	JWT refresh token lifetime
maxFileSize	1048576	Max file size for indexing (bytes)
exclude	—	Additional glob to exclude from indexing
redis.enabled	false	Enable Redis backend for session store and embedding cache
redis.url	—	Redis connection URL (redis:// or rediss:// for TLS)
redis.prefix	mgm:	Key prefix for all Redis keys
redis.embeddingCacheTtl	30d	TTL for cached embeddings in Redis

Model config

Set at server, project, or graph level. Resolution: graph → project → server → defaults (whole-object, first-defined-wins — no field-by-field merge).

The code graph has its own chain via codeModel: graphs.code.model → project.codeModel → server.codeModel → code defaults (defaults to jinaai/jina-embeddings-v2-base-code with mean pooling).

Field	Default	Description
name	Xenova/bge-m3	HuggingFace model ID
pooling	cls	mean or cls
normalize	true	L2-normalize vectors
dtype	q8	Quantization: fp32, fp16, q8, q4

Embedding config

Set at server, project, or graph level. Resolution: graph → project → server → defaults (field-by-field merge — each field individually inherits up the chain, unlike model config).

Field	Default	Description
batchSize	1	Texts per forward pass
maxChars	24000	Max characters per node
cacheSize	10000	Embedding cache size (0 = disabled)
remote	—	Remote embedding API URL
remoteApiKey	—	API key for remote endpoint
remoteModel	—	Which model to request: "default" or "code" (auto for code graph)

Per-graph settings

Each graph (docs, code, knowledge, tasks, files, skills) supports:

Field	Default	Description
enabled	true	Set false to disable entirely
readonly	false	Loaded and searchable, but mutations blocked
include	(varies)	Glob for file matching (docs/code only)
exclude	—	Additional exclude glob
model	(inherited)	Graph-specific model config
access	—	Per-user access overrides

Readonly mode

graphs:
  knowledge:
    readonly: true    # loaded + searchable, mutations blocked

Setting	Graph loaded?	Read tools	Mutation tools
enabled: false	No	Hidden	Hidden
enabled: true	Yes	Visible	Visible
readonly: true	Yes	Visible	Hidden

readonly overrides per-user rw access. See Access Control for details.

Redis configuration

By default, Graph Memory uses in-memory storage for MCP HTTP sessions and the embedding cache. For production deployments or multi-instance setups, you can use Redis instead.

server:
  redis:
    enabled: true
    url: "redis://localhost:6379"

When server.redis.enabled is true:

• MCP session store — active MCP HTTP sessions are stored in Redis instead of memory. Sessions survive server restarts and are shared across instances.
• Embedding cache — computed embeddings are cached in Redis. Vectors computed in one server instance are reused by others, and the cache persists across restarts.

Field	Default	Description
redis.enabled	false	Enable Redis backend
redis.url	—	Redis connection URL (redis:// or rediss:// for TLS)
redis.prefix	mgm:	Key prefix for all Redis keys
redis.embeddingCacheTtl	30d	TTL for cached embeddings in Redis

Set enabled: true and provide a url to activate Redis. Without enabled: true, in-memory stores are used regardless of the URL.

Applying changes

Restart the server to apply changes to graph-memory.yaml.