Skip to main content
Glama
EremesNG

Thoth-Mem

by EremesNG
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

mem_session

Records verified root session lifecycle events like enrollment, compaction checkpoints, and finalization for Thoth-Mem. Use it to persist auditable session milestones, not ordinary saves.

Instructions

Record verified root lifecycle events; never use it as an ordinary save. summary is optional and only valid for operation="checkpoint_pre_compact" with kind="checkpoint" or operation="finalize" with kind="final". summary.coverage starts at 1 and its to_sequence must advance the current ending sequence for this session and kind. Each claim's support_ids must be evidence ids from this project_key + root_session_key/harness session inside summary.coverage.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
contentNo
harnessYesVerified native harness for root_session_key in project_key.
summaryNoOptional only for operation="checkpoint_pre_compact" (kind="checkpoint") or operation="finalize" (kind="final"). coverage starts at 1 and to_sequence must advance the current summary for this session and kind. support_ids must be evidence ids from this project_key + root_session_key/harness session inside coverage. Canonical submission limit: 20000 UTF-16 units.
event_keyYesStable lifecycle event key; retries for the same operation must resend identical content/summary.
operationYesLifecycle operation; summary is allowed only for checkpoint_pre_compact (checkpoint) or finalize (final).
project_keyYesExact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.
project_nameYesCreation/display metadata only; never participates in project identity equality. Prefer the database-persisted name returned by lifecycle or project output.
root_session_keyYesStable verified root session key; required with harness for every operation.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed17 schema fields changedv0.5.6
    • removedInput schema / properties / action
      Removed value: -{
-  "description": "Session action",
-  "enum": [
-    "start",
-    "summary",
-    "checkpoint"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / content / description
      Removed value: -"Full session summary for action=summary"
    • removedInput schema / properties / directory
      Removed value: -{
-  "description": "Working directory for action=start",
-  "type": "string"
-}
    • addedInput schema / properties / event_key
      Added value: +{
+  "description": "Stable lifecycle event key; retries for the same operation must resend identical content/summary.",
+  "minLength": 1,
+  "type": "string"
+}
    • addedInput schema / properties / harness
      Added value: +{
+  "description": "Verified native harness for root_session_key in project_key.",
+  "enum": [
+    "opencode",
+    "codex",
+    "claude",
+    "pi",
+    "mcp",
+    "cli",
+    "import"
+  ],
+  "type": "string"
+}
    • removedInput schema / properties / id
      Removed value: -{
-  "description": "Session ID. Required for action=start; defaults to manual-save-{project} for summary/checkpoint",
-  "type": "string"
-}
    • addedInput schema / properties / operation
      Added value: +{
+  "description": "Lifecycle operation; summary is allowed only for checkpoint_pre_compact (checkpoint) or finalize (final).",
+  "enum": [
+    "enroll",
+    "recover",
+    "capture_root",
+    "checkpoint_pre_compact",
+    "guide_post_compact",
+    "finalize"
+  ],
+  "type": "string"
+}
    • removedInput schema / properties / project
      Removed value: -{
-  "description": "Project name",
-  "type": "string"
-}
    • addedInput schema / properties / project_key
      Added value: +{
+  "description": "Exact opaque project_key copied verbatim from verified native identity; never derive it from a display name, path hint, remote, branch, worktree name, host ID, listing, or recalled content.",
+  "minLength": 1,
+  "type": "string"
+}
    • addedInput schema / properties / project_name
      Added value: +{
+  "description": "Creation/display metadata only; never participates in project identity equality. Prefer the database-persisted name returned by lifecycle or project output.",
+  "minLength": 1,
+  "type": "string"
+}
    • addedInput schema / properties / root_session_key
      Added value: +{
+  "description": "Stable verified root session key; required with harness for every operation.",
+  "minLength": 1,
+  "type": "string"
+}
    • addedInput schema / properties / summary / additionalProperties
      Added value: +false
    • changedInput schema / properties / summary / description
      Previous value: -"Short checkpoint summary for action=checkpoint"New value: +"Optional only for operation=\"checkpoint_pre_compact\" (kind=\"checkpoint\") or operation=\"finalize\" (kind=\"final\"). coverage starts at 1 and to_sequence must advance the current summary for this session and kind. support_ids must be evidence ids from this project_key + root_session_key/harness session inside coverage. Canonical submission limit: 20000 UTF-16 units."
    • addedInput schema / properties / summary / properties
      Added value: +{
+  "claims": {
+    "description": "1-32 atomic supported claims; keep the canonical summary within 20000 UTF-16 units.",
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "content": {
+          "description": "Atomic claim content; at most 2000 code points after privacy filtering.",
+          "minLength": 1,
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "objective",
+            "completed",
+            "decision",
+            "changed_surface",
+            "verification",
+            "pending",
+            "blocker",
+            "next_action"
+          ],
+          "type": "string"
+        },
+        "outcome": {
+          "enum": [
+            "unknown",
+            "succeeded",
+            "failed",
+            "mixed"
+          ],
+          "type": "string"
+        },
+        "support_ids": {
+          "description": "1-16 distinct evidence ids from this project_key + root_session_key/harness session inside summary.coverage; never memory, summary, or observation ids.",
+          "items": {
+            "maxLength": 200,
+            "minLength": 1,
+            "type": "string"
+          },
+          "maxItems": 16,
+          "minItems": 1,
+          "type": "array"
+        }
+      },
+      "required": [
+        "kind",
+        "content",
+        "support_ids"
+      ],
+      "type": "object"
+    },
+    "maxItems": 32,
+    "minItems": 1,
+    "type": "array"
+  },
+  "coverage": {
+    "additionalProperties": false,
+    "description": "Inclusive session evidence coverage; start at 1 and advance to_sequence for this session and summary kind.",
+    "properties": {
+      "from_sequence": {
+        "description": "Inclusive first session event sequence; must start at 1.",
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "to_sequence": {
+        "description": "Inclusive last session event sequence; must be >= from_sequence and exceed the current summary ending sequence for this session and kind.",
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "from_sequence",
+      "to_sequence"
+    ],
+    "type": "object"
+  },
+  "generator": {
+    "additionalProperties": false,
+    "properties": {
+      "config_hash": {
+        "pattern": "^[0-9a-f]{64}$",
+        "type": "string"
+      },
+      "kind": {
+        "enum": [
+          "root_agent",
+          "harness",
+          "model"
+        ],
+        "type": "string"
+      },
+      "name": {
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      },
+      "version": {
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "kind",
+      "name"
+    ],
+    "type": "object"
+  },
+  "kind": {
+    "description": "Send checkpoint for operation=\"checkpoint_pre_compact\" or final for operation=\"finalize\".",
+    "enum": [
+      "checkpoint",
+      "final"
+    ],
+    "type": "string"
+  }
+}
    • addedInput schema / properties / summary / required
      Added value: +[
+  "kind",
+  "coverage",
+  "generator",
+  "claims"
+]
    • changedInput schema / properties / summary / type
      Previous value: -"string"New value: +"object"
    • changedInput schema / required
      Previous value: -[
-  "action",
-  "project"
-]New value: +[
+  "operation",
+  "harness",
+  "project_key",
+  "project_name",
+  "root_session_key",
+  "event_key"
+]
  2. Addedv0.4.13
  3. Removedv0.4.1
  4. First observedv0.3.7

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations, the description must carry the behavioral burden. It discloses important constraints around summary validity, coverage advancement, and support_ids scoping, but omits permissions, side effects, failure behavior, and the meaning of 'verified' lifecycle events.

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?

The description is compact and front-loads the core purpose before diving into summary constraints. It avoids filler, though some of its content duplicates the already-detailed schema descriptions.

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

Completeness3/5

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

For a complex lifecycle tool with nested objects and no output schema, the description covers core purpose and summary rules. It is incomplete on operation-specific semantics: enroll, recover, capture_root, and guide_post_compact are not explained, leaving invocation guidance thin for a required enum parameter.

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 88%, so the schema already documents most parameters thoroughly. The description reinforces a few nested constraints around summary, coverage, and support_ids, but adds little beyond what the schema descriptions already state.

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?

The description states a specific verb and resource: recording verified root lifecycle events. It explicitly distinguishes the tool from an ordinary save, which routes the agent away from the sibling mem_save for normal persistence.

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

Usage Guidelines4/5

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

It gives a clear exclusion ('never use it as an ordinary save') and specifies exactly when the optional summary payload is valid. However, it does not explain when to choose each lifecycle operation or name alternatives beyond the implicit ordinary-save sibling.

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

Deploy Server

Other Tools