graph-memory.yaml.example

# ============================================================================
# graph-memory.yaml — MCP Graph Memory configuration
# ============================================================================
# All fields are optional except projects.*.projectDir.
# Values shown below are the defaults — uncomment and change as needed.
# ============================================================================

# ---------------------------------------------------------------------------
# Author (default for all projects — used as createdBy/updatedBy in notes, tasks, skills)
# Can be overridden per project. Written as "Name <email>" in mirror files (git style).
# ---------------------------------------------------------------------------
# author:
#   name: "Your Name"
#   email: "you@example.com"

# ---------------------------------------------------------------------------
# Users (optional — for REST API authentication and access control)
# ---------------------------------------------------------------------------
# Each key is the user ID. apiKey is for API/MCP authentication.
# passwordHash is for UI login (email+password) — use `graphmemory users add` CLI to generate.
#
# users:
#   alice:
#     name: "Alice"
#     email: "alice@example.com"
#     apiKey: "mgm-key-abc123"
#     passwordHash: "$scrypt$65536$8$1$salt$hash"   # generated by CLI
#   bob:
#     name: "Bob"
#     email: "bob@example.com"
#     apiKey: "mgm-key-def456"
#     passwordHash: "$scrypt$65536$8$1$salt$hash"

# ---------------------------------------------------------------------------
# Server settings (shared across all projects)
# ---------------------------------------------------------------------------
server:
  # host: "127.0.0.1"                          # HTTP server bind address
  # port: 3000                                  # HTTP server port
  # sessionTimeout: 3600                        # Idle session timeout (seconds)
  # modelsDir: "~/.graph-memory/models"         # Local model cache directory
  # corsOrigins:                                # Allowed CORS origins (default: all)
  #   - "http://localhost:5173"
  #   - "https://my-app.example.com"
  # defaultAccess: rw                           # Default access for unknown users: deny | r | rw
  # access:                                     # Server-level per-user access
  #   alice: rw
  #   bob: r
  # jwtSecret: "your-secret-key-here"           # Required for UI password login (JWT signing)
  # cookieSecure: true                          # Cookie Secure flag (default: auto based on NODE_ENV)
  # accessTokenTtl: "15m"                       # JWT access token lifetime (default: 15m)
  # refreshTokenTtl: "7d"                       # JWT refresh token lifetime (default: 7d)
  # maxFileSize: 1048576                        # Max file size for indexing in bytes (default: 1 MB)

  # OAuth 2.0 settings (separate from UI JWT tokens above)
  # oauth:
  #   enabled: true                              # Enable OAuth endpoints (default: false)
  #   accessTokenTtl: "1h"                       # OAuth access token lifetime (default: 1h)
  #   refreshTokenTtl: "7d"                      # OAuth refresh token lifetime (default: 7d)
  #   authCodeTtl: "10m"                         # Authorization code TTL for PKCE flow (default: 10m)
  # exclude: "**/vendor/**"                     # Additional glob to exclude (merged with default: **/node_modules/**, **/dist/**)

  # Redis (optional — session store for OAuth codes/sessions + embedding cache)
  # Enables horizontal scaling and survives server restarts. In-memory fallback when disabled.
  # redis:
  #   enabled: false                             # Set true to enable Redis backend
  #   url: "redis://localhost:6379"              # Redis connection URL
  #   prefix: "mgm:"                            # Key prefix for all Redis keys
  #   embeddingCacheTtl: "30d"                   # TTL for cached embeddings (default: 30d, 0 = no TTL)

  # Rate limiting (requests per minute per IP)
  # rateLimit:
  #   global: 600                               # All endpoints (default: 600)
  #   search: 120                               # Search/embed endpoints (default: 120)
  #   auth: 10                                  # Login endpoints (default: 10)

  # Default model config (fallback for all graphs except code).
  # Taken as a whole object from the first level that defines it (no field-by-field merge).
  # model:
  #   name: "Xenova/bge-m3"                     # HuggingFace model ID (default: Xenova/bge-m3)
  #   pooling: "cls"                            # Pooling strategy: "mean" or "cls"
  #   normalize: true                           # L2-normalize output vectors
  #   dtype: "q8"                               # Quantization: fp32, fp16, q8, q4 (default: q8)
  #   queryPrefix: ""                           # Prefix prepended to search queries
  #   documentPrefix: ""                        # Prefix prepended to documents during indexing

  # Default model for the code graph (separate from `model`).
  # Resolution: graphs.code.model → project.codeModel → server.codeModel → code defaults
  # codeModel:
  #   name: "jinaai/jina-embeddings-v2-base-code"  # Code-optimized model (default)
  #   pooling: "mean"
  #   normalize: true
  #   dtype: "q8"

  # Default embedding config (fallback for all graphs in all projects).
  # Each field individually inherits up the chain (field-by-field merge).
  # embedding:
  #   batchSize: 1                              # Texts per ONNX forward pass (increase for faster indexing, more memory)
  #   maxChars: 24000                            # Max chars fed to embedder per node
  #   cacheSize: 10000                          # Embedding cache size (0 = disabled)
  #   remote: "http://gpu-server:3000/api/embed" # Use remote embedding API instead of local ONNX
  #   remoteApiKey: "emb-secret-key"             # API key for remote embedding
  #   remoteModel: "default"                     # Which model to request: "default" or "code" (auto-set to "code" for code graph)

  # Embedding API: expose server's embedding model via POST /api/embed
  # embeddingApi:
  #   enabled: false                             # Set true to enable
  #   apiKey: "emb-secret-key"                   # API key (separate from user apiKeys)
  #   maxTexts: 100                              # Max texts per request (default: 100)
  #   maxTextChars: 10000                        # Max chars per text (default: 10000)

# ---------------------------------------------------------------------------
# Projects
# ---------------------------------------------------------------------------
projects:

  # ── Project 1: Full-stack app with docs and source code ──────────────────
  my-app:
    projectDir: "/path/to/my-app"               # (required) Root directory to index

    # Storage
    # graphMemory: ".graph-memory"              # Graph data dir (relative to projectDir)

    # Exclude pattern (merged with server default: **/node_modules/**, **/dist/**)
    # exclude: "**/coverage/**"                 # Additional glob to exclude from indexing
    # maxFileSize: 1048576                      # Max file size (overrides server default)

    # Parsing
    # chunkDepth: 4                             # Max heading depth to chunk at

    # Per-project model config (overrides server.model — taken as whole object)
    # model:
    #   name: "Xenova/bge-m3"
    #   pooling: "cls"
    #   normalize: true

    # Per-project code model (overrides server.codeModel — separate chain for code graph)
    # codeModel:
    #   name: "jinaai/jina-embeddings-v2-base-code"
    #   pooling: "mean"
    #   normalize: true

    # Per-project embedding config (overrides server.embedding — field-by-field merge)
    # embedding:
    #   maxChars: 24000                           # Max chars fed to embedder per node

    # Per-project author (overrides root author)
    # author:
    #   name: "Project Bot"
    #   email: "bot@example.com"

    # Per-project access (overrides server.access for this project)
    # access:
    #   bob: rw                                  # bob gets rw on this project

    # Per-graph configuration
    # Each graph can be enabled/disabled, have its own include, exclude, model, and embedding.
    # Model resolution: graph.model → project.model → server.model (whole-object, first-defined-wins)
    # Code graph: graph.model → project.codeModel → server.codeModel (separate chain)
    # Embedding resolution: graph.embedding → project.embedding → server.embedding (field-by-field merge)
    # graphs:
    #   docs:
    #     enabled: true                          # default: true (set false to disable)
    #     include: "**/*.md"                     # Glob for markdown files (default: "**/*.md")
    #     exclude: "**/changelog/**"              # Additional exclude (merged with project + server)
    #     model:                                 # Full model config (no merge with parent)
    #       name: "Xenova/bge-m3"
    #       pooling: "cls"
    #       normalize: true
    #     embedding:                             # Embedding config (field-by-field merge with parent)
    #       maxChars: 16000
    #     access:
    #       charlie: rw
    #   code:
    #     enabled: true
    #     include: "**/*.{js,ts,jsx,tsx,mjs,mts,cjs,cts}"  # Glob for source files
    #     exclude: "**/generated/**"
    #   knowledge:
    #     enabled: true
    #     readonly: false                        # Set true to block all writes (overrides ACL rw → r)
    #     access:                                # Per-graph access (overrides project.access)
    #       bob: rw                              # bob gets rw on knowledge even if project says r
    #   tasks:
    #     enabled: true
    #     readonly: false
    #   files:
    #     enabled: true
    #   skills:
    #     enabled: true
    #     readonly: false

  # ── Project 2: Documentation-only project (no code indexing) ─────────────
  docs-site:
    projectDir: "/path/to/docs-site"
    exclude: "**/build/**"
    graphs:
      docs:
        include: "content/**/*.md"
      code:
        enabled: false                          # Disable code indexing
      skills:
        enabled: false                          # Disable skills

# ---------------------------------------------------------------------------
# Workspaces (optional — share knowledge/tasks/skills across projects)
# ---------------------------------------------------------------------------
# Projects in the same workspace share a single KnowledgeGraph, TaskGraph,
# and SkillGraph. Each project keeps its own DocGraph, CodeGraph, and
# FileIndexGraph. Useful for microservice repos or mono-repos.
#
# workspaces:
#   backend:
#     projects: [api-gateway, catalog-service]  # List of project IDs from above
#     graphMemory: "./.workspace-backend"       # Where shared graph JSON files are stored
#     mirrorDir: "./.workspace-backend"         # Where shared .notes/, .tasks/, .skills/ are written
#     author:                                   # Author for shared notes/tasks/skills
#       name: "Backend Team"
#       email: "backend@example.com"
#     # Workspace-level access (overrides server.access for workspace shared graphs)
#     # access:
#     #   alice: rw
#     #   bob: r
#     # maxFileSize: 1048576                    # Max file size (overrides server default)
#     # exclude: "**/vendor/**"                 # Additional exclude (merged with server default)
#     # Workspace-level model (overrides server.model for shared graphs)
#     # model:
#     #   name: "Xenova/bge-m3"
#     #   pooling: "cls"
#     #   normalize: true
#     # Workspace-level embedding (overrides server.embedding for shared graphs)
#     # embedding:
#     #   maxChars: 24000
#     # Per-graph config for shared graphs (knowledge, tasks, skills only)
#     # graphs:
#     #   knowledge:
#     #     enabled: true
#     #     model:
#     #       name: "Xenova/bge-m3"
#     #     embedding:
#     #       maxChars: 16000

# ============================================================================
# Embedding model examples
# ============================================================================
# Below are examples of how to configure different embedding models.
# Copy the relevant `model:` block into server, project, or graphs section.
#
# ── Default: BGE-M3 (recommended) ─────────────────────────────────────────
# Best general-purpose model. 1024 dimensions, multilingual (100+ languages),
# 8K token context. Works out of the box with default settings.
#
#   model:
#     name: "Xenova/bge-m3"
#     pooling: "cls"
#     normalize: true
#
# ── BGE-base (English, smaller) ───────────────────────────────────────────
# Good English-only model. 768 dimensions, faster than BGE-M3.
# Requires query prefix for best results.
#
#   model:
#     name: "Xenova/bge-base-en-v1.5"
#     pooling: "cls"
#     normalize: true
#     queryPrefix: "Represent this sentence for searching relevant passages: "
#
# ── BGE-small (English, smallest) ─────────────────────────────────────────
# Lightweight English model. 384 dimensions, fastest inference.
#
#   model:
#     name: "Xenova/bge-small-en-v1.5"
#     pooling: "cls"
#     normalize: true
#     queryPrefix: "Represent this sentence for searching relevant passages: "
#
# ── all-MiniLM-L6-v2 (legacy default) ────────────────────────────────────
# The previous default. 384 dimensions, English-only.
# No prefixes needed. Good for low-resource environments.
#
#   model:
#     name: "Xenova/all-MiniLM-L6-v2"
#     pooling: "mean"
#     normalize: true
#
# ── nomic-embed-text-v1.5 ────────────────────────────────────────────────
# High-quality model with separate query/document prefixes.
# 768 dimensions, 8K context, Matryoshka support.
#
#   model:
#     name: "nomic-ai/nomic-embed-text-v1.5"
#     pooling: "mean"
#     normalize: true
#     queryPrefix: "search_query: "
#     documentPrefix: "search_document: "
#
# ── Quantized model (lower memory usage) ─────────────────────────────────
# Use dtype to load quantized model variants for reduced memory.
# Options: fp32 (default), fp16, q8, q4
#
#   model:
#     name: "Xenova/bge-m3"
#     pooling: "cls"
#     normalize: true
#     dtype: "q8"
#
# ── Mixed config: different models per graph ──────────────────────────────
# The code graph defaults to jinaai/jina-embeddings-v2-base-code via `codeModel`.
# Other graphs default to Xenova/bge-m3 via `model`. You can override per-graph:
#
# projects:
#   my-app:
#     projectDir: "/path/to/my-app"
#     model:
#       name: "Xenova/bge-m3"                     # default for docs, knowledge, tasks, skills, files
#       pooling: "cls"
#       normalize: true
#     codeModel:
#       name: "jinaai/jina-embeddings-v2-base-code"  # default for code graph (separate chain)
#       pooling: "mean"
#       normalize: true
#     graphs:
#       files:
#         model:
#           name: "Xenova/bge-small-en-v1.5"      # smaller model for file paths
#           pooling: "cls"
#           normalize: true