iai-personal-memory-engine

Overview Schema Source Related Servers Discussions Admin

memory_capture

Capture verbatim conversation turns into personal memory with auto-dedup of near-duplicates. Use for corrections, decisions, or observations with role, tier, and salience for accurate retrieval.

Instructions

Capture a verbatim turn (auto-dedups near-duplicates). Use for corrections, not for minting standing-order directives.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`cue`	No	Short natural-language cue used for embedding + dedup lookup. If empty, `text` itself is embedded.
`goal`	No	Optional refreshed goal for the live session task, when it has moved on from the goal the task opened with. Folded verbatim onto this session's own working-tier entry after the capture completes. Empty or whitespace-only is a no-op, never a clear.
`role`	No	Who produced this turn — tags the record for filtering.	user
`text`	Yes	Verbatim text to capture (user utterance, Claude decision, or observation). Min 12 chars, max 8000 (longer is truncated).
`tier`	No	Memory tier. Default 'episodic' (verbatim user utterances). Use 'semantic' for induced summaries, 'procedural' for learned behaviour notes.	episodic
`focus`	No	Optional current point of attention for the live session task. Folded verbatim onto this session's own working-tier entry after the capture completes, alongside next_action.
`agent_id`	No	Optional id of a background agent this capture is spawning or completing. Combine with agent_role and agent_expected_artifact to register a pending agent; combine with agent_complete_id on a later call to mark it done.
`agent_role`	No	Optional role of the spawned background agent (for example 'research' or 'implement'). Required alongside agent_id and agent_expected_artifact to register a spawn; omitted otherwise.
`session_id`	No	Current session id for provenance.
`agent_model`	No	Optional model label for the spawned background agent, recorded on the registry entry when agent_id/agent_role/agent_expected_artifact register a spawn.
`next_action`	No	Optional immediate next step for the current live session task. Folded verbatim onto this session's own working-tier entry after the capture completes; surfaces at the next session start and on every subsequent turn until updated again.
`salience_level`	No	Caller-declared salience level for a decision, correction, or load-bearing preference marked in-turn. Additive rank-fusion boost only -- never a merge/drop lock. Omit for 'unflagged' (default, no behavior change). A value outside the enum is coerced to 'unflagged' server-side, never rejected.	unflagged
`epistemic_status`	No	Caller-declared epistemic status. Omit for 'unknown' (default, no behavior change). A value outside the enum is coerced to 'unknown' server-side, never rejected.	unknown
`agent_complete_id`	No	Optional id of a previously spawned background agent to mark complete on this call.
`agent_expected_artifact`	No	Optional artifact the spawned background agent is expected to produce. Required alongside agent_id and agent_role to register a spawn; omitted otherwise.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`reason`	No
`status`	No
`record_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv3.2.3Sep 15, 2026

addedInput schema / properties / goal

Added value: +{
+  "description": "Optional refreshed goal for the live session task, when it has moved on from the goal the task opened with. Folded verbatim onto this session's own working-tier entry after the capture completes. Empty or whitespace-only is a no-op, never a clear.",
+  "type": "string"
+}

Changed9 schema fields changedv3.1.0Sep 6, 2026

addedInput schema / properties / agent_complete_id

Added value: +{
+  "description": "Optional id of a previously spawned background agent to mark complete on this call.",
+  "type": "string"
+}

addedInput schema / properties / agent_expected_artifact

Added value: +{
+  "description": "Optional artifact the spawned background agent is expected to produce. Required alongside agent_id and agent_role to register a spawn; omitted otherwise.",
+  "type": "string"
+}

addedInput schema / properties / agent_id

Added value: +{
+  "description": "Optional id of a background agent this capture is spawning or completing. Combine with agent_role and agent_expected_artifact to register a pending agent; combine with agent_complete_id on a later call to mark it done.",
+  "type": "string"
+}

addedInput schema / properties / agent_model

Added value: +{
+  "description": "Optional model label for the spawned background agent, recorded on the registry entry when agent_id/agent_role/agent_expected_artifact register a spawn.",
+  "type": "string"
+}

addedInput schema / properties / agent_role

Added value: +{
+  "description": "Optional role of the spawned background agent (for example 'research' or 'implement'). Required alongside agent_id and agent_expected_artifact to register a spawn; omitted otherwise.",
+  "type": "string"
+}

addedInput schema / properties / epistemic_status

Added value: +{
+  "default": "unknown",
+  "description": "Caller-declared epistemic status. Omit for 'unknown' (default, no behavior change). A value outside the enum is coerced to 'unknown' server-side, never rejected.",
+  "enum": [
+    "fact",
+    "estimate",
+    "hypothesis",
+    "opinion",
+    "unknown"
+  ],
+  "type": "string"
+}

addedInput schema / properties / focus

Added value: +{
+  "description": "Optional current point of attention for the live session task. Folded verbatim onto this session's own working-tier entry after the capture completes, alongside next_action.",
+  "type": "string"
+}

addedInput schema / properties / next_action

Added value: +{
+  "description": "Optional immediate next step for the current live session task. Folded verbatim onto this session's own working-tier entry after the capture completes; surfaces at the next session start and on every subsequent turn until updated again.",
+  "type": "string"
+}

addedInput schema / properties / salience_level

Added value: +{
+  "default": "unflagged",
+  "description": "Caller-declared salience level for a decision, correction, or load-bearing preference marked in-turn. Additive rank-fusion boost only -- never a merge/drop lock. Omit for 'unflagged' (default, no behavior change). A value outside the enum is coerced to 'unflagged' server-side, never rejected.",
+  "enum": [
+    "unflagged",
+    "notable",
+    "critical"
+  ],
+  "type": "string"
+}

Addedv3.0.0Aug 10, 2026
Removedv2.6.1Jul 26, 2026

Changed1 schema field changedv1.0.3Jun 12, 2026

changedInput schema / properties / session_id / description

Previous value: -"Current session id for provenance (MEM-05)."New value: +"Current session id for provenance."

Changed1 schema field changedv0.2.0May 12, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "reason": {
+      "type": "string"
+    },
+    "record_id": {
+      "format": "uuid",
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "inserted",
+        "reinforced",
+        "skipped"
+      ],
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedv1.0.0May 11, 2026

TDQS

A4.4/5.0

Behavior4/5

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

With all annotations false, the description carries the burden of explaining behavior, and it does disclose the key behavior: capturing verbatim content and auto-deduping near-duplicates. It does not detail side effects on existing entries or permission requirements, but the rich schema compensates for most remaining ambiguity.

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 a single compact sentence that front-loads the core purpose and immediately adds the most important behavior and usage caveat. Every word earns its place with no redundancy.

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?

The tool is complex with 15 parameters, but the schema provides complete parameter coverage and an output schema exists, so the description need not explain return values. The description captures the essential usage boundary and dedup behavior; only a named alternative for standing-order directives would make it fully complete.

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 schema already documents all 15 parameters thoroughly. The description adds no parameter-specific detail, but since the schema handles the burden, a baseline score of 3 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?

The description names a specific action and resource ('Capture a verbatim turn') and adds the distinguishing behavior of auto-deduping near-duplicates. This clearly separates it from sibling memory tools like memory_recall or memory_search, which are read-oriented.

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?

It explicitly states when to use the tool ('Use for corrections') and when not to ('not for minting standing-order directives'). This positive and negative guidance is actionable and prevents misuse even though no specific alternative tool is named.

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

Deploy Server