Moltline Recall

Fold new facts into a memory graph and get the whole graph back. FREE. Idempotent by construction: re-adding the same entity, observation or relation changes nothing, so an agent that replays its own history does not end up with a graph full of duplicates. Typical input {"graph": {"entities": [], "relations": []}, "entities": [{"name": "Acme Corp", "type": "company", "observations": ["renewed in March"]}]} returns {"graph": {...}, "added": {"entities": 1, "observations": 1, "relations": 0}, "merged": 0}. Use as the single write path for memory. Not for reading it back selectively - that is graph_search - and not for finding out what a write changed, which graph_diff answers precisely. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": "<what is wrong and how to fix it>"} (for example {"error": "graph exceeds <value> entities; split it"}). Every call is read-only and idempotent, so after correcting the input it is always safe to retry.

{
  "type": "object",
  "properties": {
    "graph": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The existing graph document, or omitted to start a new one.\nShape: {\"entities\": [...], \"relations\": [...]}."
    },
    "entities": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Entities to add or extend, each {\"name\": ..., \"type\": ...,\n\"observations\": [...]}. Observations are appended and deduplicated;\nan existing entity keeps its type unless a new one is supplied."
    },
    "relations": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Relations to add, each {\"from\": ..., \"to\": ..., \"type\":\n..., and optionally \"since\", \"until\", \"confidence\"}. Dates are\nISO 8601 (YYYY-MM-DD); confidence is 0 to 1."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

Find what the graph knows about something, plus its neighbourhood. FREE. Scores entities by how many query words appear in the name, type and observations, then pulls in whatever is within the requested number of hops - because the useful answer to "what do we know about Acme" is usually Acme plus who it is connected to. Typical input {"graph": {...}, "query": "acme renewal", "hops": 1} returns {"matches": [{"name": "Acme Corp", "score": 3, "why": ["name", "observation"]}], "neighbourhood": {"entities": [...], "relations": [...]}, "hops": 1}. Use to read memory back before answering. Not for writing (graph_upsert) and not for narrowing by date, which graph_at_time does. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": "<what is wrong and how to fix it>"} (for example {"error": "query must contain at least one word or number"}). Every call is read-only and idempotent, so after correcting the input it is always safe to retry.

{
  "type": "object",
  "properties": {
    "graph": {
      "additionalProperties": true,
      "type": "object",
      "description": "The graph document to search."
    },
    "query": {
      "type": "string",
      "description": "Words to look for, e.g. \"acme renewal\". Matching is on whole\nlowercase words, so it is exact and repeatable rather than fuzzy."
    },
    "hops": {
      "default": 1,
      "maximum": 3,
      "minimum": 0,
      "type": "integer",
      "description": "How far to expand from each match along relations. 0 returns\nmatches only; 3 is the maximum. Default 1."
    },
    "limit": {
      "default": 20,
      "maximum": 200,
      "minimum": 1,
      "type": "integer",
      "description": "Maximum entities to return. Default 20, maximum 200."
    }
  },
  "required": [
    "graph",
    "query"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

Say exactly what changed between two versions of a memory. FREE. The audit trail a database gives you for free, without the database. Typical input {"before": {...}, "after": {...}} returns {"entities_added": ["Beta Ltd"], "entities_removed": [], "observations_added": {"Acme Corp": ["renewed in March"]}, "relations_added": [...], "changed": true}. Use after an upsert to record what a session learned, or between two agents to see what one knows that the other does not. Not for merging the two - feed the differences back through graph_upsert for that. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": "<what is wrong and how to fix it>"}. Every call is read-only and idempotent, so after correcting the input it is always safe to retry.

{
  "type": "object",
  "properties": {
    "before": {
      "additionalProperties": true,
      "type": "object",
      "description": "The earlier graph document."
    },
    "after": {
      "additionalProperties": true,
      "type": "object",
      "description": "The later graph document."
    }
  },
  "required": [
    "before",
    "after"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

Find the breaks a memory graph accumulates as it grows. FREE. Relations pointing at entities that do not exist, entities nothing points at, near-duplicate names, and observations that contradict each other on the same entity. Typical input {"graph": {...}} returns {"ok": false, "dangling_relations": [{"from": "Acme Corp", "to": "Beta Ltd", "missing": ["Beta Ltd"]}], "orphan_entities": ["Old Note"], "near_duplicates": [["Acme Corp", "Acme Corp."]], "contradictions": []}. Use before trusting a graph you did not build, or on a schedule as memory grows. Not for comparing two graphs (graph_diff) and not for shrinking one (graph_compact). Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": "<what is wrong and how to fix it>"}. Every call is read-only and idempotent, so after correcting the input it is always safe to retry.

{
  "type": "object",
  "properties": {
    "graph": {
      "additionalProperties": true,
      "type": "object",
      "description": "The graph document to check."
    }
  },
  "required": [
    "graph"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

See the memory as it stood on a given day, optionally faded by age. PREMIUM (license). Relations carrying since and until are filtered to those in force on the date; with a half-life, confidence decays exponentially with age so a two-year-old belief does not weigh the same as last week's. Typical input {"graph": {...}, "as_of": "2026-06-01", "half_life_days": 180} returns {"as_of": "2026-06-01", "graph": {...}, "dropped": {"not_yet": 1, "expired": 2}, "decayed": 4}. Use when the answer depends on when you ask. Not for what changed between two points - that is graph_diff, which does not need dates at all. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": "<what is wrong and how to fix it>"} (for example {"error": "as_of must be a date like 2026-06-01"}). Every call is read-only and idempotent, so after correcting the input it is always safe to retry.

{
  "type": "object",
  "properties": {
    "graph": {
      "additionalProperties": true,
      "type": "object",
      "description": "The graph document."
    },
    "as_of": {
      "type": "string",
      "description": "The date to view the memory as of, ISO 8601, e.g. \"2026-06-01\"."
    },
    "half_life_days": {
      "default": 0,
      "minimum": 0,
      "type": "integer",
      "description": "Days over which a relation's confidence halves. 0, the\ndefault, disables decay and leaves confidence untouched."
    }
  },
  "required": [
    "graph",
    "as_of"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

Shrink a memory to the part that still earns its place. PREMIUM (license). Ranks entities by how connected they are and how much is recorded about them, keeps anything you name outright, and drops the rest along with the relations that pointed at them. Typical input {"graph": {...}, "max_entities": 50, "keep": ["Acme Corp"]} returns {"graph": {...}, "kept": 50, "dropped_entities": ["Old Note", ...], "dropped_relations": 12, "ranking": "degree, then observation count, then name"}. Use when a graph has outgrown the context you can spend on it. Not for removing wrong facts - graph_lint finds those, and deleting them is a decision you should make deliberately rather than by ranking. Errors: on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": "<what is wrong and how to fix it>"}. Every call is read-only and idempotent, so after correcting the input it is always safe to retry.

{
  "type": "object",
  "properties": {
    "graph": {
      "additionalProperties": true,
      "type": "object",
      "description": "The graph document to compact."
    },
    "max_entities": {
      "default": 50,
      "minimum": 1,
      "type": "integer",
      "description": "How many entities to keep. Default 50."
    },
    "keep": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Entity names to keep regardless of rank, e.g. [\"Acme Corp\"].\nMatched case-insensitively."
    }
  },
  "required": [
    "graph"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}