memory_pin

Mark a fact as pinned — exempt from decay, exempt from consolidation, always returned by recall. Use sparingly: this is the agent declaring “this is canonical, never lose it”.

Input

{
  "factId": "fact_xxx",
  "pinned": true
}

Output

{
  "id": "fact_xxx",
  "pinned": true,
  "pinnedAt": "2026-06-07T18:22:00Z",
  "pinCount": 4
}

pinCount is the total number of currently pinned facts in the workspace. Mnemosyne enforces a soft limit (50 by default) — pinning shouldn’t be used as the primary retention strategy.

When the agent should pin

• Canonical workspace truth: “the production cluster URL is X”.
• Critical user constraint: “Lucas is allergic to peanuts”.
• A strategy that the user explicitly endorsed.

When the agent should NOT pin

• High-volume informational facts (use Worth instead — it converges).
• Personal preferences that may change (the bitemporal model handles that).
• Just to “make sure it’s remembered” — that defeats the gating.

Lifecycle interaction

• Pinned facts are excluded from the Consolidation gate even when worth is low.
• Pinned facts are excluded from the decay function.
• Pinned facts still respect bitemporal validity — closing one resets its valid_to like any other.