1.0 Operator Playbook for Coding Agents
Most MentisDB users will not write a custom Rust agent. They will use OpenCode, Codex, Claude Code, Cursor, or another MCP-capable coding harness. This chapter is the operator manual for that world: what to prompt, when to make the agent search, when to make it write, and how to make memory compound instead of turning into a noisy log.
The goal: each day the agent should start with more useful project context
than it had yesterday. MentisDB does not make the model smarter by magic. It makes the
right prior decisions, traps, preferences, and lessons available at the right moment.
The One Prompt That Starts Memory
Paste this at the start of a new repository session:
Use MentisDB as your durable memory system for this repository.
Before doing work:
1. Find or bootstrap the correct project chain.
2. Read the core MentisDB skill/instructions.
3. Load recent context and the latest checkpoint.
4. Search for prior decisions, constraints, mistakes, and lessons related to this task.
5. Tell me what you found before editing files.
During work:
- Search before adding new memories.
- Save only information that will matter in a future session: decisions, constraints, lessons, mistakes, preferences, completed work, and checkpoints.
- When saving, include concrete names: files, commands, subsystems, errors, and the reason the memory matters.
- If the new memory depends on something already in MentisDB, connect it to the older context you found.
Before stopping:
- Write a checkpoint with what changed, what passed, what failed, and the exact next step.This prompt matters because most agents will happily use MentisDB as a write-only notebook unless you tell them to load, search, reason, and then write. The retrieval step is where performance improves.
The Daily Memory Loop
Use this loop for every meaningful coding session:
- Start: bootstrap the chain, load recent context, find the latest checkpoint.
- Orient: search for the topic, files, subsystem, error, and prior decisions.
- Work: edit code, run tests, debug, review.
- Distill: identify what future agents should know.
- Write: append only durable, typed memories with tags and concepts.
- Checkpoint: save a resumable summary before context loss or session end.
Before you edit, search MentisDB for:
- prior decisions about this subsystem
- mistakes or failed fixes involving these files
- user preferences for this repo
- constraints that should affect the implementation
Summarize the relevant memories and then proceed.When To Use MentisDB
| Moment | Ask the agent to do this | Why |
|---|---|---|
| New session | Bootstrap, read skill, recent context, latest checkpoint | Prevents cold-start amnesia |
| Before unfamiliar edits | Search decisions, constraints, lessons, mistakes | Avoids repeating known traps |
| After root cause found | Ask the agent to save the root cause and verified fix as a durable lesson | Makes the failure useful tomorrow |
| After architectural choice | Ask the agent to remember the choice, rationale, and rejected alternatives | Stops re-litigating the same choice |
| After tests pass | Ask the agent to save what changed and the exact verification result | Gives future agents evidence |
| Before compaction | Ask the agent to write a resumable checkpoint | Survives context truncation |
| Before handoff | Ask the agent to save what is done, what is risky, and the next action | Lets another agent resume cleanly |
What To Save, What To Skip
Save
- A decision and why it was made.
- A constraint that should affect future work.
- A mistake, root cause, and correction.
- A user preference that changes how the agent should behave.
- A completed task with exact verification evidence.
- A checkpoint that lets a future session resume.
Skip
- Raw command logs without interpretation.
- Temporary hunches that were not validated.
- Generic notes like "working on tests".
- Duplicate summaries already present in the chain.
- Secrets, tokens, credentials, or private keys.
Bad Memory vs Good Memory
Bad:
Remember that tests passed.Good:
Save this in MentisDB as a durable completion note, but first search for related websocket reconnect work so you do not duplicate an existing memory.
We implemented retry jitter for websocket reconnects. `cargo test websocket_reconnect` passed. The follow-up is to run the full integration suite before release.Bad:
Remember not to do that again.Good:
Remember the lesson from this bug so future agents do not repeat it. Search MentisDB for related dashboard deletion or stale-data mistakes first, then save the root cause, the bad fix, and the safe fix.
The lesson: do not fix dashboard stale data by recreating deleted chains when the cache is dropped. That regressed delete semantics. The safe fix is to detach persistence before deleting cached chains.The Prompt Pack
Start a task
Before implementing this, search MentisDB for prior decisions, constraints, mistakes, and lessons about this area. Report the top relevant memories with their thought types, then proceed.Debug a failure
Search MentisDB for this error message, failing test name, file path, and subsystem. Look especially for prior mistakes, corrections, lessons, and completed fixes. Do not propose a fix until you summarize what previous work says.Record a durable lesson
Save the root cause and fix in MentisDB as a durable lesson. Include exact file paths, the failed assumption, the verified fix, and links to any related prior mistake or checkpoint you find when searching.Before context loss
Write a resumable MentisDB checkpoint now. Include: goal, completed work, files changed, tests run and results, unresolved risks, and the first next step.Improve the agent's behavior
If this lesson will apply repeatedly, propose whether it should become a MentisDB skill. If yes, draft the skill update and remember why we decided to make it a skill instead of leaving it as one more project memory.Harness-Specific Tricks
OpenCode
- Keep a project skill or instruction that says "search MentisDB before edits".
- Ask for a memory summary before large refactors.
- After a long tool run, explicitly ask for a checkpoint before continuing.
- If subagents are used, tell each one the chain and agent identity to use.
Codex
- Use a task-start prompt that requires searching before writing code.
- Ask Codex to cite memories by type and content summary, not by vague "I remember" claims.
- Ask it to save completed work only after verification output is known.
Claude Code
- Use MentisDB at the start of every repository session, not only after the context fills.
- Ask for a handoff checkpoint before switching from Claude Code to another harness.
- Prefer stdio for local Claude Desktop and HTTP/HTTPS MCP for shared daemon setups.
How To Tell If It Is Working
- The agent mentions relevant prior decisions before editing.
- The same mistake is not repeated across sessions.
- Checkpoints contain exact next steps, not vague summaries.
- Search results improve because thoughts have strong tags and concepts.
- Repeated lessons become skills, not just more memories.
Anti-pattern: "Use MentisDB" is not enough. A model can satisfy that by
appending noisy notes. The operator's job is to enforce the loop: search first, work,
distill, write only durable memories, checkpoint.
The Compounding Effect
Day one, MentisDB mostly remembers setup and decisions. Day two, it prevents repeated mistakes. Day three, it carries user preferences and verification history. Day four, it turns repeated lessons into skills. Day five, a different model or harness can inherit the same project memory. That is the power curve: not one smarter model, but a better memory substrate that every model can use.