Thoth-Mem

Overview Schema Source Related Servers Discussions Admin

mem_save

Save verified decisions, discoveries, failures, conventions, and handoffs to persistent memory so AI coding agents can recall them across sessions.

Instructions

Save verified durable decisions, discoveries, failures, conventions, and continuation handoffs. For a direct promoted memory other than a handoff, write memory.content as concise labeled Result, Rationale, Scope, and Caveat / safe action lines. Omit Scope or Caveat / safe action when it does not apply, and never invent details to fill the template. Keep evidence compact and factual. Handoff memories keep the dedicated Objective, Completed, First pending action, Blockers, and Key files/checks format and require a stable workstream topic_key; close a finished handoff by saving its outcome under the same topic_key. Send exactly one branch: evidence (optionally + memory for a direct promoted save; structured evidence with metadata forbids memory and requires event_key plus the session pair), observation (requires event_key; session scope also requires the session pair and coverage), observation_review or observation_promotion (each requires event_key plus the session pair). Supply root_session_key and harness together or omit both.

Input Schema

TableJSON Schema

Name	Required	Description
`memory`	No	Promoted memory for direct evidence only; requires evidence without metadata. Do not combine with observation, observation_review, or observation_promotion.
`harness`	No	Native harness for root_session_key; supply both or omit both. Required wherever root_session_key is required.
`evidence`	No	Direct evidence { kind, content }; optionally add memory for a promoted save. Structured metadata forbids memory and requires event_key, root_session_key, and harness.
`event_key`	No	Stable event key for idempotency; required for observation, observation_review, observation_promotion, and evidence with metadata.
`observation`	No	Submit a supported candidate without promotion; requires event_key. Session scope also requires root_session_key, harness, and coverage.
`project_key`	Yes	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.
`project_name`	Yes	Creation/display metadata only; never participates in project identity equality. Prefer the database-persisted name returned by lifecycle or project output.
`root_session_key`	No	Verified root session key; supply with harness or omit both. Required for session-scoped observations, observation_review, observation_promotion, and evidence with metadata; blank counts as absent.
`observation_review`	No	Review one supported observation; requires event_key, root_session_key, and harness. Send no other operation branch or memory.
`observation_promotion`	No	Promote one accepted observation without new prose; requires event_key, root_session_key, and harness. Send no other operation branch or memory.

Schema Changelog

Changes observed during successful MCP inspections.

Changed19 schema fields changedv0.5.6Oct 4, 2026

removedInput schema / properties / content

Removed value: -{
-  "description": "Memory content, prompt text, session summary, or text containing a Key Learnings section",
-  "type": "string"
-}

addedInput schema / properties / event_key

Added value: +{
+  "description": "Stable event key for idempotency; required for observation, observation_review, observation_promotion, and evidence with metadata.",
+  "type": "string"
+}

addedInput schema / properties / evidence

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "content": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "root_prompt",
+            "explicit_save",
+            "checkpoint",
+            "handoff",
+            "legacy_prompt",
+            "legacy_observation",
+            "session_summary"
+          ],
+          "type": "string"
+        },
+        "source_ref": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "content"
+      ],
+      "type": "object"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "content": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "kind": {
+          "const": "explicit_save",
+          "type": "string"
+        },
+        "metadata": {
+          "additionalProperties": false,
+          "properties": {
+            "observation_validation": {
+              "additionalProperties": false,
+              "properties": {
+                "method": {
+                  "maxLength": 500,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "observation_id": {
+                  "maxLength": 200,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "result": {
+                  "enum": [
+                    "passed",
+                    "failed"
+                  ],
+                  "type": "string"
+                }
+              },
+              "required": [
+                "observation_id",
+                "result",
+                "method"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "observation_validation"
+          ],
+          "type": "object"
+        },
+        "source_ref": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "content",
+        "metadata"
+      ],
+      "type": "object"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "content": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "kind": {
+          "const": "handoff",
+          "type": "string"
+        },
+        "metadata": {
+          "additionalProperties": false,
+          "properties": {
+            "observation_review_attestation": {
+              "additionalProperties": false,
+              "properties": {
+                "method": {
+                  "maxLength": 500,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "observation_id": {
+                  "maxLength": 200,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "reviewer": {
+                  "maxLength": 200,
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "verdict": {
+                  "enum": [
+                    "accepted",
+                    "rejected"
+                  ],
+                  "type": "string"
+                }
+              },
+              "required": [
+                "observation_id",
+                "verdict",
+                "reviewer",
+                "method"
+              ],
+              "type": "object"
+            }
+          },
+          "required": [
+            "observation_review_attestation"
+          ],
+          "type": "object"
+        },
+        "source_ref": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "content",
+        "metadata"
+      ],
+      "type": "object"
+    }
+  ],
+  "description": "Direct evidence { kind, content }; optionally add memory for a promoted save. Structured metadata forbids memory and requires event_key, root_session_key, and harness."
+}

addedInput schema / properties / harness

Added value: +{
+  "description": "Native harness for root_session_key; supply both or omit both. Required wherever root_session_key is required.",
+  "enum": [
+    "opencode",
+    "codex",
+    "claude",
+    "pi",
+    "mcp",
+    "cli",
+    "import"
+  ],
+  "type": "string"
+}

removedInput schema / properties / kind

Removed value: -{
-  "description": "Write mode. Defaults to observation",
-  "enum": [
-    "observation",
-    "prompt",
-    "session_summary",
-    "passive_learnings"
-  ],
-  "type": "string"
-}

addedInput schema / properties / memory

Added value: +{
+  "additionalProperties": false,
+  "description": "Promoted memory for direct evidence only; requires evidence without metadata. Do not combine with observation, observation_review, or observation_promotion.",
+  "properties": {
+    "content": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "kind": {
+      "enum": [
+        "decision",
+        "convention",
+        "architecture",
+        "discovery",
+        "failure",
+        "project_structure",
+        "handoff",
+        "preference"
+      ],
+      "type": "string"
+    },
+    "outcome": {
+      "enum": [
+        "unknown",
+        "succeeded",
+        "failed",
+        "mixed"
+      ],
+      "type": "string"
+    },
+    "supersedes_id": {
+      "type": "string"
+    },
+    "title": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "topic_key": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "kind",
+    "title",
+    "content"
+  ],
+  "type": "object"
+}

addedInput schema / properties / observation

Added value: +{
+  "additionalProperties": false,
+  "description": "Submit a supported candidate without promotion; requires event_key. Session scope also requires root_session_key, harness, and coverage.",
+  "properties": {
+    "claim": {
+      "maxLength": 4000,
+      "minLength": 1,
+      "type": "string"
+    },
+    "concepts": {
+      "items": {
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      },
+      "maxItems": 16,
+      "type": "array"
+    },
+    "coverage": {
+      "additionalProperties": false,
+      "properties": {
+        "from_sequence": {
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991,
+          "type": "integer"
+        },
+        "to_sequence": {
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "from_sequence",
+        "to_sequence"
+      ],
+      "type": "object"
+    },
+    "files": {
+      "items": {
+        "maxLength": 500,
+        "minLength": 1,
+        "type": "string"
+      },
+      "maxItems": 16,
+      "type": "array"
+    },
+    "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": {
+      "enum": [
+        "decision",
+        "constraint",
+        "fact",
+        "procedure",
+        "result",
+        "failure",
+        "preference"
+      ],
+      "type": "string"
+    },
+    "predecessor_id": {
+      "maxLength": 200,
+      "minLength": 1,
+      "type": "string"
+    },
+    "proposed_memory": {
+      "additionalProperties": false,
+      "properties": {
+        "content": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "decision",
+            "convention",
+            "architecture",
+            "discovery",
+            "failure",
+            "project_structure",
+            "handoff",
+            "preference"
+          ],
+          "type": "string"
+        },
+        "outcome": {
+          "enum": [
+            "unknown",
+            "succeeded",
+            "failed",
+            "mixed"
+          ],
+          "type": "string"
+        },
+        "title": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "topic_key": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "title",
+        "content"
+      ],
+      "type": "object"
+    },
+    "scope": {
+      "enum": [
+        "session",
+        "project"
+      ],
+      "type": "string"
+    },
+    "support_ids": {
+      "items": {
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      },
+      "maxItems": 16,
+      "minItems": 1,
+      "type": "array"
+    },
+    "title": {
+      "maxLength": 500,
+      "minLength": 1,
+      "type": "string"
+    }
+  },
+  "required": [
+    "kind",
+    "scope",
+    "title",
+    "claim",
+    "proposed_memory",
+    "support_ids",
+    "generator"
+  ],
+  "type": "object"
+}

addedInput schema / properties / observation_promotion

Added value: +{
+  "additionalProperties": false,
+  "description": "Promote one accepted observation without new prose; requires event_key, root_session_key, and harness. Send no other operation branch or memory.",
+  "properties": {
+    "observation_id": {
+      "maxLength": 200,
+      "minLength": 1,
+      "type": "string"
+    }
+  },
+  "required": [
+    "observation_id"
+  ],
+  "type": "object"
+}

addedInput schema / properties / observation_review

Added value: +{
+  "additionalProperties": false,
+  "description": "Review one supported observation; requires event_key, root_session_key, and harness. Send no other operation branch or memory.",
+  "properties": {
+    "basis": {
+      "enum": [
+        "root_user_confirmed",
+        "observable_validation",
+        "independent_review"
+      ],
+      "type": "string"
+    },
+    "observation_id": {
+      "maxLength": 200,
+      "minLength": 1,
+      "type": "string"
+    },
+    "policy": {
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "maxLength": 200,
+          "minLength": 1,
+          "type": "string"
+        },
+        "version": {
+          "maxLength": 200,
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "version"
+      ],
+      "type": "object"
+    },
+    "reason": {
+      "maxLength": 1000,
+      "minLength": 1,
+      "type": "string"
+    },
+    "support_ids": {
+      "items": {
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      },
+      "maxItems": 16,
+      "minItems": 1,
+      "type": "array"
+    },
+    "verdict": {
+      "enum": [
+        "accepted",
+        "rejected"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "observation_id",
+    "verdict",
+    "basis",
+    "policy",
+    "reason",
+    "support_ids"
+  ],
+  "type": "object"
+}

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": "Verified root session key; supply with harness or omit both. Required for session-scoped observations, observation_review, observation_promotion, and evidence with metadata; blank counts as absent.",
+  "type": "string"
+}

removedInput schema / properties / scope

Removed value: -{
-  "description": "Observation scope",
-  "enum": [
-    "project",
-    "personal"
-  ],
-  "type": "string"
-}

removedInput schema / properties / session_id

Removed value: -{
-  "description": "Session ID (default: manual-save-{project})",
-  "type": "string"
-}

removedInput schema / properties / title

Removed value: -{
-  "description": "Short searchable title. Required for kind=observation",
-  "type": "string"
-}

removedInput schema / properties / topic_key

Removed value: -{
-  "description": "Stable key for observation upserts",
-  "type": "string"
-}

removedInput schema / properties / type

Removed value: -{
-  "description": "Observation category for kind=observation",
-  "enum": [
-    "decision",
-    "architecture",
-    "bugfix",
-    "pattern",
-    "config",
-    "discovery",
-    "learning",
-    "session_summary",
-    "manual"
-  ],
-  "type": "string"
-}

changedInput schema / required

Previous value: -[
-  "content"
-]New value: +[
+  "project_key",
+  "project_name"
+]

Addedv0.4.13Aug 21, 2026
Removedv0.4.1Jul 20, 2026
First observedv0.3.7Jul 11, 2026

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses that structured evidence forbids memory, that a finished handoff is closed by re-saving its outcome under the same topic_key, that root_session_key and harness must be supplied together or omitted together, and that details must never be invented. It stops short of describing idempotency behavior (event_key semantics) or the return/confirmation shape, which would round out the behavioral picture.

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

Conciseness3/5

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

The purpose is front-loaded, but the branch rules are compressed into one very long parenthetical sentence ('Send exactly one branch: evidence (optionally + memory ...), observation (requires event_key; session scope also requires ...) ...') with no bullets or line breaks. For a four-branch mutually-exclusive contract, the prose is denser and harder to parse than the complexity warrants, even though most sentences carry real information.

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?

For a 10-parameter, deeply nested, no-annotation tool with no output schema, the description covers the essentials an agent needs: branch selection, the memory/handoff content formats, the session-pair coupling, and the metadata/memory prohibition. It omits confirmation/return behavior and idempotency semantics, but with no output schema those are secondary.

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 baseline is 3, but the description adds real meaning beyond the schema: the memory.content template (Result, Rationale, Scope, Caveat / safe action lines with an explicit 'omit when not applicable' rule), the dedicated handoff format, and the stable-topic_key closing rule for handoffs. The cross-parameter coupling constraints (memory only with metadata-free evidence; session pair + coverage for session-scoped observations) are semantics the schema cannot express.

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?

Opens with a specific verb+resource ('Save verified durable decisions, discoveries, failures, conventions, and continuation handoffs'), so the write scope is unambiguous against the read-oriented siblings (mem_get, mem_recall). It does not explicitly name or contrast a sibling, but the save-vs-retrieve distinction is self-evident from the enumerated artifact types.

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 enumerates the four mutually exclusive branches (evidence, observation, observation_review, observation_promotion) and states 'Send exactly one branch,' with per-branch prerequisites (event_key, session pair, coverage) attached to each. This is as close to a decision tree as a description gets, leaving nothing to inference.

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

Deploy Server

mem_save

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools