Skip to main content
Glama

extract_memories

Extracts structured preferences, facts, and skills from conversation text using rule-based or LLM semantic matching, with optional auto-save into a persistent shared memory store.

Instructions

Extract structured memories from conversation text. mode="rule" (default) detects preferences, facts, and skills via keyword pattern matching. mode="llm" instead understands the full context (optionally pairing assistant_text) semantically — uses the configured LLM extraction provider, and degrades to rule-based extraction (reported via fallback_used/fallback_reason) when no provider is configured or the LLM call fails. Returns extracted items; with auto_save=true it also writes them through delta-write (near-identical memories are merged or skipped, not duplicated) and requires agent auth when the agent has a registered key. Use save_memory instead when you already know the exact memory to store. Invalid occurred_at is an error, never a silent drop.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "text": "<text>"
    },
    "name": "extract_memories"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNoExtraction mode: "rule" (default, keyword pattern matching) or "llm" (semantic extraction over the full context; uses the configured LLM extraction provider, falling back to rule-based when none is configured or the LLM call fails — see fallback_used in the result).
textYesText to extract memories from (conversation content, e.g. the user's turn)
api_keyNoAPI key for agent authentication (required if agent has a registered key)
agent_idNoAgent ID to attribute saved memories tounknown
auto_saveNoWhether to auto-save extracted memories
fact_writeNopreserve (default); resolve requires auto_save plus explicit assertions and keyed actor.
occurred_atNoWhen the extracted facts actually happened in the source conversation (RFC 3339), stored as `occurred_at` on saved memories — distinct from `created_at` (ingestion time). Invalid input is an error, never a silent drop.
assistant_textNoOptional paired assistant/response text for mode="llm" — passing both sides of the exchange lets the model resolve references and implicit preferences a single text can't.
fact_assertionsNoExplicit assertion per extracted item, positionally matched; null leaves an item unasserted. No automatic subject/property keys are generated from plaintext.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.7.2
    • addedInput schema / $defs
      Added value: +{
      +  "FactAssertionInput": {
      +    "additionalProperties": false,
      +    "description": "Local wire DTOs keep schema-generation dependencies out of the core.",
      +    "properties": {
      +      "cardinality": {
      +        "$ref": "#/$defs/FactCardinalityInput"
      +      },
      +      "key": {
      +        "description": "Stable caller-supplied subject/property/qualifier identity; never inferred.",
      +        "type": "string"
      +      },
      +      "source_namespace": {
      +        "type": "string"
      +      },
      +      "source_order": {
      +        "description": "Comparable ordinal within this producer/source stream (not a timestamp).",
      +        "format": "uint64",
      +        "minimum": 0,
      +        "type": "integer"
      +      },
      +      "value": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "key",
      +      "value",
      +      "source_namespace",
      +      "source_order",
      +      "cardinality"
      +    ],
      +    "type": "object"
      +  },
      +  "FactCardinalityInput": {
      +    "enum": [
      +      "single",
      +      "multi",
      +      "event",
      +      "unknown"
      +    ],
      +    "type": "string"
      +  },
      +  "FactWriteInput": {
      +    "enum": [
      +      "preserve",
      +      "resolve"
      +    ],
      +    "type": "string"
      +  }
      +}
    • addedInput schema / properties / fact_assertions
      Added value: +{
      +  "description": "Explicit assertion per extracted item, positionally matched; null leaves an item unasserted.\nNo automatic subject/property keys are generated from plaintext.",
      +  "items": {
      +    "anyOf": [
      +      {
      +        "$ref": "#/$defs/FactAssertionInput"
      +      },
      +      {
      +        "type": "null"
      +      }
      +    ]
      +  },
      +  "type": [
      +    "array",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / fact_write
      Added value: +{
      +  "$ref": "#/$defs/FactWriteInput",
      +  "description": "preserve (default); resolve requires auto_save plus explicit assertions and keyed actor."
      +}
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare the read/write safety profile, so the description carries the real behavioral load and does: LLM-mode degradation to rule matching with fallback_used/fallback_reason reporting, delta-write dedup that merges or skips near-identical memories, agent-key auth requirement, and invalid occurred_at as an error rather than a silent drop. That is context an agent cannot get from the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and zero filler sentences; every clause carries information. Slightly denser than ideal, packing modes, fallback, dedup, auth, and error semantics into one semicolon-chained paragraph rather than scanning bullets.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter tool with optional writes and no output schema, the description still tells the agent what comes back (extracted items, fallback_used/fallback_reason) and what side effects auto_save causes. Nothing needed to call it correctly is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter constraints the schema does not express — resolve requires auto_save plus explicit assertions and a keyed actor, and assistant_text only matters with mode="llm". Defaults and field-level meaning are left to the already-complete schema, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

A specific verb-plus-resource ("Extract structured memories from conversation text"), immediately qualified by the two extraction modes, and explicitly differentiated from save_memory. An agent can distinguish this from every sibling that stores or edits a known memory without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes away: "Use save_memory instead when you already know the exact memory to store." It also states when to pick mode="llm" over the rule default, when auto_save triggers a write, and what fact_write="resolve" requires — conditions rather than inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.