Skip to main content
Glama

save_memory

Persist user preferences, facts, episodes, or skills so agents recall them in future sessions. Near-duplicate saves are merged or skipped automatically, and embeddings are generated for semantic search.

Instructions

Save a new memory. Memories are persistent user preferences, facts, episodes, or skills that should be recalled in future conversations. Embeddings are generated automatically for semantic search. Delta-write is on by default: near-duplicate saves are skipped and similar existing memories absorb the new content instead of a new row being created (status in the response: saved | merged | skipped). Pass force_insert=true to bypass. Writes persist immediately; requires agent auth when the agent has a registered key.

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": {
      "content": "<content>"
    },
    "name": "save_memory"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagsNoTags for categorization
typeNoMemory type: preference, fact, episode, entity, or skillfact
layerNoMemory layer: L0 (raw), L1 (atom), L2 (scenario), L3 (persona). Auto-assigned if omitted.
api_keyNoAPI key for agent authentication (required if agent has a registered key)
contentYesThe content of the memory to save
agent_idNoID of the agent saving this memoryunknown
priorityNoPriority level: MUST, REFERENCE, or BACKGROUNDREFERENCE
namespaceNoNamespace for the memory (default: global)global
agent_typeNoType of the agent (e.g., coding-assistant)general-assistant
confidenceNoConfidence score (0.0 to 1.0)
expires_atNoValid-time bound (RFC3339): when this fact stops being true, e.g. `2026-12-31T00:00:00Z`. Once past, the memory leaves retrieval and injection but stays inspectable and restorable — expiry retires a fact, only `forget_memory` erases one. Use for inherently temporary facts ("the deploy freeze runs until Friday") so they retire themselves instead of decaying slowly and being re-injected as stale truth. Omit for anything not time-bounded.
fact_writeNopreserve (default) or resolve (atomic, requires a verified keyed producer). force_insert=true takes precedence and leaves the new row unmanaged.
visibilityNoSharing scope: "scoped" (default, namespace rules) or "shared" (team pool).
instructionNoOptional instruction format for the memory
occurred_atNoWhen the remembered fact actually happened in the source conversation/document (RFC 3339) — **event-time**, a separate axis from `created_at` (ingest-time) and from `expires_at` (valid-time). Set this when saving something that happened earlier than now, e.g. backfilling a dated transcript; without it a batch import stamps every row "now" and all event timing is lost. Invalid input is an error, never a silent drop.
skill_stepsNoSkill execution steps (only for type=skill)
force_insertNoForce insert, skipping delta-write dedup/merge. By default a save is checked against similar memories in the same namespace: near-duplicates are skipped, similar memories absorb the new content's residual (docs/DESIGN.md §9.1.1).
skill_triggerNoSkill trigger pattern (only for type=skill)
fact_assertionNoExplicit caller-supplied fact identity/value/source metadata; never inferred from text.
skill_verificationNoSkill verification criteria (only for type=skill)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 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 / expires_at
      Added value: +{
      +  "default": null,
      +  "description": "Valid-time bound (RFC3339): when this fact stops being true, e.g.\n`2026-12-31T00:00:00Z`. Once past, the memory leaves retrieval and\ninjection but stays inspectable and restorable — expiry retires a fact,\nonly `forget_memory` erases one. Use for inherently temporary facts\n(\"the deploy freeze runs until Friday\") so they retire themselves instead\nof decaying slowly and being re-injected as stale truth. Omit for\nanything not time-bounded.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / fact_assertion
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/FactAssertionInput"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Explicit caller-supplied fact identity/value/source metadata; never inferred from text."
      +}
    • addedInput schema / properties / fact_write
      Added value: +{
      +  "$ref": "#/$defs/FactWriteInput",
      +  "description": "preserve (default) or resolve (atomic, requires a verified keyed producer).\nforce_insert=true takes precedence and leaves the new row unmanaged."
      +}
    • changedInput schema / properties / force_insert / description
      Previous value: -"Force insert, skipping delta-write dedup/merge. By default a save is\nchecked against similar memories in the same namespace: near-duplicates\nare skipped, similar memories absorb the new content's residual\n(docs/DESIGN.md §17.1)."New value: +"Force insert, skipping delta-write dedup/merge. By default a save is\nchecked against similar memories in the same namespace: near-duplicates\nare skipped, similar memories absorb the new content's residual\n(docs/DESIGN.md §9.1.1)."
    • addedInput schema / properties / occurred_at
      Added value: +{
      +  "default": null,
      +  "description": "When the remembered fact actually happened in the source\nconversation/document (RFC 3339) — **event-time**, a separate axis from\n`created_at` (ingest-time) and from `expires_at` (valid-time). Set this\nwhen saving something that happened earlier than now, e.g. backfilling a\ndated transcript; without it a batch import stamps every row \"now\" and all\nevent timing is lost. Invalid input is an error, never a silent drop.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  2. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

The annotations already declare that this is a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds substantial context beyond that: embeddings are automatic, delta-write deduplicates and may merge or skip saves, response statuses are saved/merged/skipped, writes persist immediately, and auth is required for keyed agents. It does not cover every edge case, but it materially improves behavioral understanding.

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

Conciseness5/5

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

The description is front-loaded with the core action, then layers in memory scope, delta-write behavior, and auth constraints without filler. Every sentence contributes operational information, and the parenthetical status list is compact and useful.

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

Completeness4/5

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

This is a complex write tool with 20 parameters, no output schema, and existing annotations, so the description needs to carry key behavioral context. It covers mutation, deduplication, merge/skip outcomes, immediate persistence, and auth, while the schema fully covers parameters. Minor gaps around error modes or exact merge effects remain, but the definition is complete enough to invoke correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the input schema already documents all 20 parameters in detail. The description adds useful meaning around force_insert and authentication requirements, but it does not reinterpret most parameters beyond what the schema already provides. This meets the baseline for high schema coverage.

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

Purpose4/5

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

The description opens with a specific verb and resource, 'Save a new memory,' and defines memories as persistent preferences, facts, episodes, or skills. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as propose_memory_edit or add_evidence.

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

Usage Guidelines3/5

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

Usage is implied by 'Save a new memory' and by explanations of when to use force_insert=true, but the description gives no explicit when-to-use guidance versus alternatives and no exclusions. An agent can infer the basic context but must rely on sibling names and its own judgment for routing.

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