Skip to main content
Glama

Create Memory Checkpoint

engram_reflect

Checkpoint a milestone or handoff for later recovery with engram_rehydrate. Supply at least one of summary, learnings, used_memories or feedback. Returns Markdown with stored/skipped counts, outcomes and next actions. Use engram_store for one lesson and engram_report_outcome for one outcome.

store=false skips learning storage only: the journal and supplied outcomes/feedback can still be written. This checkpoint leaves the session open. Retrying may duplicate writes; verify prior success first. Consumes workspace daily call quota and memory quota for saved lessons. OAuth: session:write, memory:write and outcome:write.

Input Schema

NameRequiredDescriptionDefault
repoNoRepository slug, e.g. engram or billing-api, within the authenticated workspace. This is a memory filter, not a filesystem path or workspace selector.
taskNoConcrete current goal or decision, e.g. diagnose checkout retries; used to focus context and session recovery.
storeNoDefault true saves accepted durable learnings; false skips learning storage only. Session checkpoints, supplied outcomes and feedback are still recorded.
summaryNoMilestone/handoff summary: what changed, evidence, decisions and remaining work. Required unless learnings, outcomes or feedback are supplied.
feedbackNoOptional product feedback or feedback-pulse dismissal; separate from outcomes about individual memories.
learningsNoDurable private workspace lessons to persist when store=true; only the first 8 are processed. Low-quality entries may be skipped. The summary remains a journal checkpoint.
agent_toolNoCalling client name for attribution, e.g. codex, claude-code, cursor, or gemini. Omit if unknown.
session_idNoExact journal id from start/rehydrate/list_sessions. Disambiguates parallel work; writing requires your active session. Rehydrate may read shared or closed history.
used_memoriesNoOutcomes for memories actually used during this milestone; only the first 20 are processed. Omit when none were applied.

Output Schema

NameRequiredDescriptionDefault
textYesThe same bounded payload as content[0].text; interpret it using format. JSON text contains the endpoint-specific fields described by this tool.
formatYesPayload encoding: Markdown context/checkpoint, serialized JSON data, or plain confirmation text.
truncatedYesTrue when the payload exceeded 120,000 characters and was cut with a notice. Narrow the request; truncated JSON is not parseable.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / session_id
      Added value: +{
      +  "description": "Exact journal id from start/rehydrate/list_sessions. Disambiguates parallel work; writing requires your active session. Rehydrate may read shared or closed history.",
      +  "type": "string"
      +}
  2. Changed22 schema fields changed
    • addedInput schema / properties / agent_tool / description
      Added value: +"Calling client name for attribution, e.g. codex, claude-code, cursor, or gemini. Omit if unknown."
    • addedInput schema / properties / feedback / description
      Added value: +"Optional product feedback or feedback-pulse dismissal; separate from outcomes about individual memories."
    • addedInput schema / properties / feedback / properties / dismiss / description
      Added value: +"True permanently dismisses the optional weekly feedback pulse for this agent member."
    • addedInput schema / properties / feedback / properties / notes / description
      Added value: +"Concrete non-sensitive feedback explaining the selected signal."
    • addedInput schema / properties / feedback / properties / signal / description
      Added value: +"Quality of Engram retrieval during this work; omit if only dismissing the feedback pulse."
    • addedInput schema / properties / learnings / description
      Added value: +"Durable private workspace lessons to persist when store=true; only the first 8 are processed. Low-quality entries may be skipped. The summary remains a journal checkpoint."
    • addedInput schema / properties / learnings / items / properties / content / description
      Added value: +"One durable, self-contained lesson, up to 20,000 characters. State the decision/fix and why it matters; exclude secrets and transient debug logs."
    • addedInput schema / properties / learnings / items / properties / content / maxLength
      Added value: +20000
    • addedInput schema / properties / learnings / items / properties / context / description
      Added value: +"Non-sensitive supporting metadata, e.g. {language: \"typescript\", component: \"auth\"}; never credentials or raw customer data."
    • addedInput schema / properties / learnings / items / properties / tags / description
      Added value: +"Topic labels for storing or filtering memory; omit when no useful labels apply."
    • addedInput schema / properties / learnings / items / properties / tags / items / description
      Added value: +"Searchable topic label, e.g. oauth or postgres."
    • addedInput schema / properties / learnings / items / properties / type / description
      Added value: +"Knowledge category: team rule, reusable pattern, pitfall, proven fix, design decision, or library/version quirk."
    • addedInput schema / properties / repo / description
      Added value: +"Repository slug, e.g. engram or billing-api, within the authenticated workspace. This is a memory filter, not a filesystem path or workspace selector."
    • addedInput schema / properties / store / description
      Added value: +"Default true saves accepted durable learnings; false skips learning storage only. Session checkpoints, supplied outcomes and feedback are still recorded."
    • addedInput schema / properties / summary / description
      Added value: +"Milestone/handoff summary: what changed, evidence, decisions and remaining work. Required unless learnings, outcomes or feedback are supplied."
    • addedInput schema / properties / task / description
      Added value: +"Concrete current goal or decision, e.g. diagnose checkout retries; used to focus context and session recovery."
    • addedInput schema / properties / used_memories / description
      Added value: +"Outcomes for memories actually used during this milestone; only the first 20 are processed. Omit when none were applied."
    • addedInput schema / properties / used_memories / items / properties / detail / description
      Added value: +"Brief evidence of how the memory changed the decision, or why it failed. Exclude secrets."
    • addedInput schema / properties / used_memories / items / properties / failure_reason / description
      Added value: +"Why an unsuccessful memory failed; outdated marks obsolete knowledge. Omit for a successful use."
    • addedInput schema / properties / used_memories / items / properties / memory_id / description
      Added value: +"Exact id from a recalled memory; do not substitute a repository name, URL, or the memory text."
    • addedInput schema / properties / used_memories / items / properties / success / description
      Added value: +"Whether this memory helped the actual task: true for a useful application, false for a misleading or unusable result."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "format": {
      +      "description": "Payload encoding: Markdown context/checkpoint, serialized JSON data, or plain confirmation text.",
      +      "enum": [
      +        "markdown",
      +        "json",
      +        "text"
      +      ],
      +      "type": "string"
      +    },
      +    "text": {
      +      "description": "The same bounded payload as content[0].text; interpret it using format. JSON text contains the endpoint-specific fields described by this tool.",
      +      "type": "string"
      +    },
      +    "truncated": {
      +      "description": "True when the payload exceeded 120,000 characters and was cut with a notice. Narrow the request; truncated JSON is not parseable.",
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "text",
      +    "format",
      +    "truncated"
      +  ],
      +  "type": "object"
      +}
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly=false and idempotent=false, but the description goes further with quota consumption, required OAuth scopes, session-state behavior ('leaves the session open'), and a retry/duplication warning. This is exactly the operational context annotations cannot carry.

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 purpose, then constraints, then operational caveats; every sentence carries distinct information for a 9-parameter mutation tool. It is dense rather than padded, though the OAuth/quota sentence stack is heavy relative to the two guiding sentences at the top.

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?

Output schema exists, yet the description still sketches the return shape (stored/skipped counts, outcomes, next actions), and it covers quotas, auth scopes, session persistence and non-idempotent retries. An agent has everything needed to call it safely and interpret the result.

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 real meaning beyond the schema: the cross-parameter constraint that at least one of four fields must be supplied (required list is empty), and the subtle store=false semantics that only affect learning storage while journal/outcomes/feedback still persist.

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?

States a specific verb and resource ('Checkpoint a milestone or handoff') plus the downstream purpose ('later recovery with engram_rehydrate'). It explicitly distinguishes itself from engram_store and engram_report_outcome, so an agent can route correctly without opening sibling schemas.

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?

Gives an explicit precondition ('Supply at least one of summary, learnings, used_memories or feedback') and names the alternatives with their selecting conditions: engram_store for one lesson, engram_report_outcome for one outcome. It also states what this tool does that the alternatives don't (bundled journal checkpoint).

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources