gingko-operator

Gingko Operator Tools

The gingko CLI handles the daily recall + record loop. This skill covers operator-grade operations that live on MCP only: branch-isolated memory, clusters, the project charter, maintenance, and mid-workflow flush. Invoke only when the user explicitly asks.

Discovering IDs

Most MCP tools want project_id. Get it from the shell:

gingko memory project-id       # e.g. "github.com--edlontech--gingko-mem"
gingko memory session-id       # active session UUID, empty if none

Branch-aware Memory

Fork a feature branch's memory off main so unmerged scratchwork doesn't pollute the shared graph. List, fork, merge, inspect, prune.

mcp__plugin_gingko_gingko__list_branches
  project_id: "<id>"

mcp__plugin_gingko_gingko__fork_branch
  project_id: "<id>"
  branch_name: "<git branch>"
  from_branch: "main"     # optional

mcp__plugin_gingko_gingko__get_merge_state
  project_id: "<id>"
  branch_name: "<source>"
  into: "<target>"

mcp__plugin_gingko_gingko__merge_branch
  project_id: "<id>"
  branch_name: "<source branch>"
  into: "main"
  strategy: "fast-forward" | "three-way"

mcp__plugin_gingko_gingko__prune_branch_memory
  project_id: "<id>"
  branch_name: "<branch>"

The session-start hook auto-detects the current git branch when starting a session, so most users never need to call fork_branch by hand — only when reorganizing memory across branches.

Clusters

Clusters are curated headline summaries — the canonical view of a topic. Recall is granular search; clusters are the table of contents. Slugs come from the cluster index printed by gingko memory session-primer.

mcp__plugin_gingko_gingko__get_cluster
  project_id: "<id>"
  slug: "auth-middleware"

Project Charter

The charter is the project's North Star — what it's for, what it isn't. Set it when the user articulates a durable mission, not on speculation.

mcp__plugin_gingko_gingko__set_charter
  project_id: "<id>"
  content: "<markdown>"

Mid-workflow Flush

Before a multi-hour operation or a hard context switch within one session, force a commit so the work persists:

mcp__plugin_gingko_gingko__commit_session
  session_id: "<current>"

The MCP call returns a fresh session_id — replace any cached value. The CLI equivalent closes the session entirely:

gingko memory close-session     # commits and clears the active session pointer

After close-session, lifecycle hooks do not auto-rerun mid-session. To start a new session immediately, use mcp__plugin_gingko_gingko__start_session.

Maintenance

Background graph hygiene. Decay weakens stale links, consolidate merges near-duplicates, validate checks integrity.

mcp__plugin_gingko_gingko__run_maintenance
  project_id: "<id>"
  operation: "decay" | "consolidate" | "validate"

mcp__plugin_gingko_gingko__refresh_principal_memory
  project_id: "<id>"
  scope: "all" | "state" | "cluster"

refresh_principal_memory regenerates the summary regions in the primer on demand — normally it regenerates itself, but a forced refresh is useful after a large bulk import.

Failure Modes

• Service unreachable — MCP calls return an error. Surface it to the user; do not retry silently.
• Wrong project_id — derived from the origin git remote. If multiple remotes or recently re-pointed, verify with git remote -v and gingko memory project-id.
• fork_branch on a branch with existing memory — operation fails; either pick a fresh name or prune_branch_memory first (destructive).