Agent Guide

Why Write to MentisDB

Your context window is temporary. MentisDB is permanent. Every important decision, lesson, or constraint you write to MentisDB is available to every future version of you — and to every other agent in your fleet.

Write the rule behind the work, not the whole story of the work.

What Deserves a Memory

Write to MentisDB when one of these becomes true:

  • You found a non-obvious bug cause another agent would likely hit again
  • You made an architectural decision that downstream work should not re-litigate
  • You discovered a trust boundary, unsafe default, or systemic risk
  • You established a stable project convention or naming rule
  • You corrected an older assumption that is now dangerous
  • You reached a restart point and need the next session to pick up quickly

Do NOT write: raw transcripts, every action you took, duplicate git history, secrets or tokens.

Choosing Thought Types

Use the semantic type that matches the memory's job:

Decision

Chosen design or implementation direction

Constraint

Hard boundary that must not drift

LessonLearned

Retrospective rule distilled from a failure

Insight

Non-obvious technical lesson

Correction

An earlier assumption was wrong; this replaces it

Summary

Compressed state; pair with role Checkpoint for restart points

PreferenceUpdate

Stable team or user preference

Question

Unresolved issue worth preserving

Retrieval Patterns

Start with recent context

At the start of every session, call mentisdb_recent_context(last_n=30). This gives you the team's latest decisions, active constraints, and lessons learned.

Search by project first

Use tags to narrow: search by project tag first, then by subsystem. Example: tags_any=["myproject"] + thought_types=["Decision","Constraint"]

Traverse for ordered history

Use mentisdb_traverse_thoughts with anchor_boundary="genesis", direction="forward" when you need oldest-to-newest replay. Use anchor_boundary="head", direction="backward" for recent-first review.

Load corrections before acting

Before making significant changes, search for thought_types=["Correction"] to make sure you're not acting on outdated assumptions.

Context Window Protocol

When your context window reaches ~50% capacity:

  1. Write a Summary checkpoint to MentisDB with tag context-checkpoint — capture what's done, what's in progress, what remains, any blockers
  2. Flush any pending LessonLearned, Decision, or Correction thoughts
  3. Compact your context (/compact or equivalent)
  4. Reload: call mentisdb_recent_context(last_n=30)
  5. Resume from where you left off — zero knowledge loss

Fleet Coordination

In a fleet, one agent acts as project manager (PM). The PM decomposes work into parallel tasks, dispatches specialist agents pre-warmed with shared memory, and synthesizes results.

As a specialist agent in a fleet:

  • Call mentisdb_recent_context at the start of your task
  • Write a Summary thought before returning (include tag context-checkpoint)
  • Use your own stable agent_id for all writes
  • Prefer targeted writes (one specific lesson per thought) over broad dumps