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.

Session Bootstrap

When a user (or your system prompt) says:

use mentisdb as your memory system

perform the following sequence automatically:

1. Call mentisdb_list_chains to discover existing chains. Match the chain whose name most closely corresponds to the current project, repository, or working directory. If no chains exist yet, ask the user for a name (the repo or project name works well).
2. Call mentisdb_bootstrap(chain_key="<chosen-key>") to open the chain and receive the available skills list. This is safe on existing chains — it will not overwrite prior memory. Only pass a meaningful content argument if you are creating a brand-new chain.
3. Immediately load the core operating instructions via resources/read(mentisdb://skill/core) (or mentisdb_skill_md as fallback). Do this before reading any memory — the skill teaches you how to interpret and write what you are about to load.
4. Call mentisdb_list_agents and pick the existing specialist identity whose role best matches the current task. Reuse it — do not mint a new identity unless the chain truly lacks the role.
5. Call mentisdb_recent_context as that agent to recover where things left off.
6. Write a Summary checkpoint to durable memory so subsequent agents can recover state without re-priming.

This is also the recommended pattern to use in your system prompt or project instructions file — any new agent session will automatically prime itself without the user needing to ask.

For advanced configurations, you can still specify a chain_key explicitly during the bootstrap call.

Choosing Thought Types

ThoughtType is the semantic label for what changed in the agent's internal model. There are 29 types grouped by purpose. Pick the one that best matches the memory's meaning — this is what makes the chain queryable and meaningful to other agents.

🧑 About the User

🔬 Observations & Knowledge

⚠️ Errors & Corrections

🗺️ Planning & Decisions

💡 Exploration & Ideas

✅ Actions & Progress

📍 State & Continuity

Thought Roles

If thought_type answers what kind of memory is this?, then role answers how is the system using it?. Roles are lifecycle and operational markers — they let you filter by purpose rather than semantics, and drive system-level behaviour like context compression and handoffs.

The default role is Memory. Only set a role when you need the chain to express something beyond plain durable memory.

roles=["Checkpoint","Handoff","Summary"]

roles=["Retrospective"] + tags=["your-project"]

Retrieval Patterns

Start with recent context

After loading mentisdb://skill/core and choosing the right chain, call mentisdb_recent_context(last_n=30). This gives you the team's latest decisions, active constraints, and lessons learned. If the chain was ambiguous, compare recent context from the top candidates before appending anything new.

Search by project first

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

Use ranked search when you remember the gist, not the exact words

Use mentisdb_ranked_search when you need the best flat matches for a topic, paraphrase, or partial recollection. In 0.8.0 this is seamless hybrid retrieval: lexical + graph signals plus vector-sidecar similarity when a managed sidecar is enabled for the chain. It returns ranking diagnostics such as backend, score.vector, matched_terms, match_sources, graph_distance, and score breakdowns so you can inspect why a memory surfaced.

Point-in-time queries with as_of

Pass as_of (an RFC 3339 timestamp) to mentisdb_ranked_search or mentisdb_traverse_thoughts to see only thoughts that existed at that point in time. Thoughts appended after the timestamp are excluded. Use this when you need to understand what was known at a specific moment — for example, why a decision was made before a later correction was appended.

Scope-filtered search

Pass scope to search and traversal tools to filter results to a specific memory scope. scope: "User" returns globally visible thoughts; scope: "Session" limits to the current session's working memory; scope: "Agent" returns only your own private memories. See the Memory Scopes section for details.

Use context bundles when supporting context matters as much as the seed

Use mentisdb_context_bundles when you want the best lexical seed thoughts plus grouped support beneath each seed. This is the right tool for understanding the decision together with the follow-on summaries, corrections, or implementation notes that hang off it through refs and typed relations.

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", "Reframe"] to make sure you're not acting on outdated assumptions or stale framings. A Reframe thought tells you that a prior memory is still factually correct but should be interpreted differently — load these alongside Corrections.

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

Skills Registry

The Skills Registry is a versioned, append-only library of reusable agent skills. Each skill is a Markdown or JSON document that describes a technique, workflow, or domain-specific procedure your fleet can load at runtime. Skills are immutable once uploaded — every edit creates a new version, and the full history is always retrievable.

How It Works

• Each skill has a stable skill_id (derived from the skill name if not specified explicitly).
• Uploading the same skill_id a second time creates version 2, version 3, and so on — it never overwrites.
• Only the uploader agent matters for provenance — any agent with the right agent_id can create new versions unless the skill is signed (see below).
• Skills can be marked deprecated (still readable, superseded) or revoked (untrusted, should not be used).

Skill Document Format (Markdown)

The recommended format is Markdown with YAML-like frontmatter. The frontmatter block is delimited by --- and supports these fields:

---
name: my-skill
description: One sentence on when and why to use this skill.
tags: [rust, axum, api]
triggers: ["when building an API", "when adding endpoints"]
warnings: ["Review rate limits before deploying"]
---

# My Skill

Brief intro paragraph.

## When to Use

Describe the conditions.

## Steps

Numbered procedure.

• name — becomes the stable skill_id slug (required)
• description — surfaced in search results; required
• tags — free-form list; used in tag-based searches
• triggers — phrases or domains that should suggest this skill to a planning agent
• warnings — safety notes; shown to the agent before execution

Uploading a Skill (MCP)

Use mentisdb_upload_skill to publish or update a skill. Your agent_id must already be registered in the chain.

mentisdb_upload_skill(
agent_id: "orion",
content: "--- ...frontmatter... ---\n\n# My Skill\n...",
format: "markdown"      // or "json"
skill_id: "my-skill",   // optional; derived from name if omitted
chain_key: "default"    // optional
)

Calling mentisdb_upload_skill with an existing skill_id automatically creates the next version — no separate upsert call needed.

A human operator can perform the same versioned edit from the web dashboard: click Edit in the Skills table or Edit Skill on a skill detail page. The dashboard saves through the upload path, so history remains immutable.

Finding and Reading Skills

• mentisdb_list_skills — returns a summary list of all skills in the registry (id, name, description, version count, status)
• mentisdb_search_skill(text: "rust api") — full-text search across name, description, headings, and body
• mentisdb_search_skill(tags_any: ["axum"]) — filter by tag
• mentisdb_search_skill(triggers_any: ["when building an API"]) — match against trigger phrases
• mentisdb_read_skill(skill_id: "my-skill") — read latest version. Returns { content, warnings, status } where content is the rendered skill text, warnings is an array of safety notices from the frontmatter, and status is the lifecycle status (active, deprecated, or revoked). Always check warnings before executing skill content.
• mentisdb_read_skill(skill_id: "my-skill", version_id: "<uuid>") — read a specific historical version (same return shape)
• mentisdb_skill_versions(skill_id: "my-skill") — list all versions with metadata (uploader, timestamp, hash)

Lifecycle Management

• mentisdb_deprecate_skill(skill_id: "my-skill", reason: "superseded by v2") — mark as superseded but still readable
• mentisdb_revoke_skill(skill_id: "my-skill", reason: "security issue") — mark as untrusted; agents should refuse to execute it

Cryptographically Signed Skills

Once an agent registers an Ed25519 public key on their identity, every skill upload from that agent requires a valid signature. The server verifies the signature before accepting the upload. This means only the original key-holder can publish new versions — even if another agent uses the same skill_id, the server will reject it.

Step 1 — Register a Public Key

Call mentisdb_add_agent_key to bind an Ed25519 public key to your agent identity:

mentisdb_add_agent_key(
agent_id:         "orion",
key_id:           "orion-signing-key-1",
algorithm:        "ed25519",
public_key_bytes: [<32 raw bytes>]
)

Step 2 — Sign the Skill Content

Produce a detached Ed25519 signature over the raw skill content bytes (not a hash — the full UTF-8 bytes of the Markdown or JSON string) using your private key. The signature must be exactly 64 bytes.

Step 3 — Upload with Signature

mentisdb_upload_skill(
agent_id:        "orion",
content:         "--- ...frontmatter... ---\n\n# My Skill\n...",
format:          "markdown",
skill_id:        "orion-secret-skill",
signing_key_id:  "orion-signing-key-1",
skill_signature: [<64 raw Ed25519 signature bytes>]
)

The server will verify the signature against the registered public key. If it does not match, the upload is rejected with an error. All future version uploads for this skill must also be signed by the same key (or a non-revoked replacement key registered to the same agent).

Best Practices for Skills

• Keep each skill focused on one reusable procedure. A 200-line skill is too broad; split it.
• Use triggers aggressively — they help planning agents auto-select the right skill during task decomposition.
• After a hard-won fix, distil the lesson into a skill so every future agent starts with the knowledge.
• Deprecate rather than delete when a skill is superseded — old versions are audit history.
• Sign any skill that other agents should not be able to tamper with.

Web Dashboard

The web dashboard (https://127.0.0.1:9475/dashboard) is a browser UI for the human operator — it has no MCP endpoint and you do not interact with it directly. However, understanding what it provides helps you direct users to the right tool when they need to inspect, debug, or manage the memory system.

What You Can Tell Users About Each Section

Chains

"Your operator can use the Chain Manager at https://127.0.0.1:9475/dashboard to see all chains with live thought and agent counts. If the page appears empty, suggest they click ↺ Refresh. Newly appended thoughts should appear without restarting mentisdb."

Thought Explorer

"The Thought Explorer lets your operator browse every thought you have written, paginated and filterable by all 29 ThoughtTypes. It also supports chain-scoped text search with a live agent dropdown, ranked results, and grouped support context bundles. Ranked search uses lexical + graph + vector hybrid scoring automatically when the chain has an enabled managed vector sidecar. This is the first place to look when debugging unexpected behavior — they can confirm what decisions and lessons are actually recorded versus what you believe you wrote. Each thought's detail modal shows positional back-references (displayed as #N) and typed relations (displayed as kind → target_id (chain: other-chain) for cross-chain edges)."

Vector Sidecars

"Each chain page also has a Vector Sidecars panel. Operators can enable/disable append-time auto-sync per provider, run Sync now, or Rebuild from scratch with an explicit delete-and-recreate confirmation. If auto-sync is disabled, sidecars can go stale; the panel reports freshness so users can resync before semantic recall quality drifts."

Agent Manager

"The Agent page shows how many thoughts you have written and lets the operator view or edit your registered identity — display name, description, owner, and signing keys. If your agent_id appears wrong, your description is missing, or you need a key rotated, this is where to do it. The latest-thoughts list should also stay current while the daemon is running."

Skills Registry

"The Skills Registry shows all skills including deprecated and revoked ones. If a skill is causing problems or was uploaded incorrectly, the operator can edit it into a new immutable version directly from the Skills table or skill detail page, or revoke it via the dashboard without any API calls. Revoked skills are preserved for audit but agents should not execute them."

Thought Relations & Cross-chain References

Beyond positional back-references (refs: [2, 5]), MentisDB supports typed semantic relations between thoughts via ThoughtRelation. A relation carries a kind (the semantic edge type), a target_id (UUID of the target thought), and an optional chain_key for cross-chain references.

Supersedes — the canonical replacement edge

Use Supersedes when a new thought replaces an older one that was correct but is now outdated. Pair it with the Reframe ThoughtType:

// Old thought #12 said X, new framing says Y.
mentisdb_append(
thought_type: "Reframe",
content: "We now frame this as Y instead of X.",
relations: [{ kind: "Supersedes", target_id: "<uuid-of-thought-12>" }]
)

Cross-chain references

A ThoughtRelation can point to a thought in a different chain by setting the optional chain_key field:

mentisdb_append(
thought_type: "Decision",
content: "Adopted the caching strategy defined in the platform chain.",
relations: [{
kind: "Supersedes",
target_id: "<uuid-of-thought-in-other-chain>",
chain_key: "platform-conventions"
}]
)

Intra-chain relations (no chain_key) remain backward-compatible. Cross-chain relations are stored as typed edges — they are visible in the dashboard thought detail modal as kind → target_id (chain: other-chain).

ContinuesFrom — sequential session chaining

Use ContinuesFrom to chain consecutive turns within a conversation session. Each turn's target_id points to the previous turn's UUID. This creates a traversable graph of session turns that graph-aware ranked search can walk when retrieving context.

mentisdb_append(
thought_type: "Observation",
content: "The retry logic resolved the timeout — root cause was DNS.",
relations: [{ kind: "ContinuesFrom", target_id: "<uuid-of-prior-turn>" }]
)

All relation kinds

Accepted values for kind in relations:

• References — generic pointer
• Summarizes — condenses the target
• Corrects — fixes a factual error in the target
• Invalidates — target no longer applies
• CausedBy — this thought resulted from the target
• Supports — provides evidence for the target
• Contradicts — conflicts with the target
• DerivedFrom — derived from the target
• ContinuesFrom — sequential continuation (session chaining)
• RelatedTo — weak associative link
• Supersedes — replaces the target's framing

Positional back-references

Positional refs (refs: [2, 5]) reference thoughts by their append-order index within the same chain. They are shown in the dashboard modal as #2, #5. Use positional refs for lightweight 'this thought follows from those' links; use typed relations when the semantic edge matters.

Bulk Import: mentisdb_import_memory_markdown

If you have an existing MEMORY.md file from a prior session (or any MentisDB-style Markdown export), you can bulk-import its contents into a chain using the mentisdb_import_memory_markdown MCP tool.

What it does

• Parses a MEMORY.md Markdown document — each heading section becomes a new thought
• Appends all parsed thoughts to the specified chain under the given default_agent_id
• Returns a count of imported thoughts

Usage

mentisdb_import_memory_markdown(
markdown: "<full contents of your MEMORY.md>",
default_agent_id: "orion",
chain_key: "my-project"   // optional; uses default chain if omitted
)

The same operation is also available via the dashboard — open a chain detail page and click 📥 Import MEMORY.md. Human operators can use this without any MCP or API access.

Backup & Restore for Agent Continuity

Your memories are durable only if the chain they live in survives. MentisDB backs up and restores via two CLI commands on the daemon host: mentisdb backup and mentisdb restore. As an agent, you do not run these yourself — the human operator runs them. But you should understand why they matter so you can recommend them at the right moments.

Why backup matters for agents

• Continuity after failure. If the daemon crashes or the host is restarted, the operator can restore from the most recent archive and you resume exactly where the chain left off — no thought loss.
• Disaster recovery. Chain data lives on disk. Hardware failure, accidental deletion, or a botched migration can wipe months of accumulated context. A current backup means the team starts over from a known checkpoint, not from zero.
• Chain migration between environments. Moving a fleet from a development host to a production host requires exporting the chain data, copying the archive, and restoring it on the target. Backups are the mechanism for that migration.
• Destructive operation safety. Before any chain merge, deletion, or storage reformat, the operator should back up first. If something goes wrong, the backup lets you recover the pre-operation state.

How backup works

The operator runs mentisdb backup on the host. This produces a .mentis ZIP archive containing all chain data (binary ledgers, agent registry, skills registry, vector sidecars) plus a SHA-256 manifest so integrity can be verified after copy.

mentisdb backup
    # Archive → ./mentisdb-2026-04-28-153022.mentis
    mentisdb backup -o /tmp/my-mentisdb-backup.mentis
    # Archive → /tmp/my-mentisdb-backup.mentis

If the daemon is running at the time of backup, the operator can pass --flush to force a durability flush before archiving, ensuring all committed thoughts are on disk.

The --flush flag and you

When --flush is passed, mentisdb backup detects if the daemon is running and calls POST /v1/admin/flush before packaging the archive. This matters because if you have appended thoughts in the last few milliseconds, the binary writer may not have flushed them to disk yet. Flushing first ensures the archive captures your latest work.

When to recommend a backup to the user

Recommend the operator run a backup before:

• Any chain merge (mentisdb_merge_chains — the source chain is deleted)
• Any chain deletion via the dashboard or API
• A daemon self-update that includes storage format changes
• Migrating the chain to a new machine or environment
• Any bulk operation that rewrites many thoughts at once

Restore and chain migration

The restore command extracts a .mentis archive to a target directory. If files already exist in the target, the operator is prompted unless --overwrite or --yes is passed.

mentisdb restore /tmp/my-mentisdb-backup.mentis
    # Interactive: asks about each conflicting file
    mentisdb restore /tmp/my-mentisdb-backup.mentis --overwrite
    # Non-interactive: overwrites without prompting

When restoring to a new machine, omit --include-tls (TLS material is machine-specific). MentisDB will auto-generate a new certificate on first start.

What is included and excluded

• Included: all binary chain ledgers, agent registry, skill registry, vector sidecar data, configuration snapshots.
• Excluded by default: TLS certificates and private keys (tls/ directory) — use --include-tls only when restoring to the same physical machine.

Memory Scopes

MentisDB 0.8.2 introduces memory scopes — a way to partition thoughts within a chain by visibility level, without creating separate chains. Scopes are stored as tags and filterable in search.

Scope levels

• User — visible across all sessions. Default scope. Tag: scope:user
• Session — scoped to a single conversation session. Ephemeral working memory. Tag: scope:session
• Agent — private to a specific agent. Not shared with other fleet members. Tag: scope:agent

Setting scope on append

Pass the scope parameter to mentisdb_append. MentisDB stores the scope as a tag on the thought.

mentisdb_append(
thought_type: "WorkingMemory",
content: "Scratch: trying cache-aside pattern",
scope: "Session"           // optional; default is User
)

Filtering by scope in search

Pass scope to any search or traversal tool to filter results:

mentisdb_ranked_search(
text: "caching strategy",
scope: "User"             // only globally visible memories
)

MCP Tool Reference

The following tools have dedicated usage patterns beyond the inline mentions elsewhere in this guide. Each entry includes the tool name, description, parameters, and return type. For mentisdb_append, note the scope parameter (0.8.2) which sets the memory scope as a tag. For search tools, note the as_of parameter for point-in-time queries, scope for scope-filtered results, and enable_reranking / rerank_k for RRF reranking (0.8.6). Use mentisdb_branch_from to create an isolated branch chain for experiments — searches on the branch transparently include ancestor chain results.

mentisdb_get_thought

Return one committed thought by stable UUID, hash, or append-order index. Use this when you know the exact identifier of a thought you need to retrieve — for example, after seeing a thought_id in a search result or a refs array.

mentisdb_get_thought(
chain_key: "my-project",    // optional
thought_id: "<uuid>",        // one of thought_id, thought_hash, or thought_index
thought_hash: "<hex>",       // stable chain hash
thought_index: 7              // append-order index
)

Parameters:

• chain_key (string, optional) — durable chain key
• thought_id (string, optional) — stable UUID of the thought
• thought_hash (string, optional) — stable chain hash
• thought_index (integer, optional) — append-order index

Returns: a single thought object with all fields (id, hash, index, type, role, content, agent, tags, concepts, refs, relations, timestamps, importance, confidence).

mentisdb_get_genesis_thought

Return the first committed thought in append order, if the chain is non-empty. Useful for recovering the bootstrap or founding memory of a chain.

mentisdb_get_genesis_thought(
chain_key: "my-project"     // optional
)

Parameters:

• chain_key (string, optional) — durable chain key

Returns: the first thought object in the chain, or an error if the chain is empty.

mentisdb_traverse_thoughts

Traverse thoughts in append order from an anchor, moving forward or backward in filtered chunks. This is the most flexible ordered-access tool — use it for oldest-to-newest replay, recent-first review, or paginated browsing with rich filters.

mentisdb_traverse_thoughts(
chain_key: "my-project",              // optional
anchor_boundary: "genesis",            // "genesis" or "head"
anchor_id: "<uuid>",                   // optional UUID anchor
anchor_hash: "<hex>",                  // optional hash anchor
anchor_index: 0,                        // optional index anchor
direction: "forward",                  // "forward" or "backward"
include_anchor: true,                   // include the anchor thought
chunk_size: 50,                         // max thoughts per page
text: "caching",                       // optional text filter
thought_types: ["Decision"],            // optional type filter
roles: ["Checkpoint"],                 // optional role filter
tags_any: ["myproject"],               // optional tag filter
concepts_any: ["auth"],                // optional concept filter
agent_ids: ["orion"],                  // optional agent filter
agent_names: ["Orion"],                // optional agent name filter
agent_owners: ["team-a"],              // optional owner filter
min_importance: 0.5,                    // optional importance threshold
min_confidence: 0.7,                    // optional confidence threshold
since: "2025-01-01T00:00:00Z",         // optional RFC 3339 lower bound
until: "2025-12-31T23:59:59Z",         // optional RFC 3339 upper bound
time_window: { start: 7, delta: 1, unit: "days" }  // optional numeric window
)

Parameters:

• chain_key (string, optional) — durable chain key
• anchor_id (string, optional) — UUID anchor
• anchor_hash (string, optional) — hash anchor
• anchor_index (integer, optional) — append-order index anchor
• anchor_boundary (string, optional) — logical anchor: genesis or head</li> <li><code></code>(string, optional) -<code></code>or<code></code>
• include_anchor (boolean, optional) — include the anchor if it matches the filter
• chunk_size (integer, optional) — max matching thoughts per call (default 50)
• text (string, optional) — text filter
• thought_types (string[], optional) — ThoughtType names
• roles (string[], optional) — ThoughtRole names
• tags_any (string[], optional) — tags to match
• concepts_any (string[], optional) — concepts to match
• agent_ids (string[], optional) — producing agent ids
• agent_names (string[], optional) — producing agent names or aliases
• agent_owners (string[], optional) — producing agent owners
• min_importance (number, optional) — minimum importance threshold
• min_confidence (number, optional) — minimum confidence threshold
• since (string, optional) — RFC 3339 lower timestamp bound
• until (string, optional) — RFC 3339 upper timestamp bound
• time_window (object, optional) — numeric time window with start, delta, unit fields

Returns: a paginated list of thought objects matching the filter, ordered by traversal direction from the anchor.

mentisdb_get_agent

Return the full registry record for one agent in a chain, including description, aliases, public keys, status, and per-chain activity metadata. Use this when you need to inspect an agent's identity details — for example, to verify which signing keys are active before rotating.

mentisdb_get_agent(
chain_key: "my-project",    // optional
agent_id: "orion"           // required
)

Parameters:

• chain_key (string, optional) — durable chain key
• agent_id (string, required) — stable agent id to retrieve

Returns: an agent record with agent_id, display_name, description, owner, aliases, public_keys, status, and activity metadata.

mentisdb_list_agent_registry

Return the full per-chain agent registry, including descriptions, aliases, public keys, status, and per-chain activity metadata for every registered agent. Unlike mentisdb_list_agents which returns a lightweight identity summary, this tool returns the complete registry record for each agent.

mentisdb_list_agent_registry(
chain_key: "my-project"     // optional
)

Parameters:

• chain_key (string, optional) — durable chain key

Returns: an array of full agent records (same shape as mentisdb_get_agent) for every registered agent on the chain.

mentisdb_set_agent_description

Set or clear the free-form description for one registered agent. Use this to document what an agent does so other agents (and the dashboard) can display meaningful context.

mentisdb_set_agent_description(
chain_key: "my-project",       // optional
agent_id: "orion",             // required
description: "Code review specialist"  // omit or empty string to clear
)

Parameters:

• chain_key (string, optional) — durable chain key
• agent_id (string, required) — stable agent id to update
• description (string, optional) — description text; omit or empty to clear

Returns: the updated agent record.

mentisdb_add_agent_alias

Add one historical or alternate alias to a registered agent. Aliases help resolve agent name changes — for example, when an agent was renamed but older thoughts still reference the prior name.

mentisdb_add_agent_alias(
chain_key: "my-project",    // optional
agent_id: "orion",          // required
alias: "orion-v1"           // required
)

Parameters:

• chain_key (string, optional) — durable chain key
• agent_id (string, required) — stable agent id to update
• alias (string, required) — alias to add

Returns: the updated agent record with the new alias included.

mentisdb_disable_agent

Disable one agent by marking its registry status as revoked. The agent's existing thoughts remain in the chain (append-only storage), but the agent identity is flagged as inactive. Use this when decommissioning an agent from a fleet.

mentisdb_disable_agent(
chain_key: "my-project",    // optional
agent_id: "legacy-bot"      // required
)

Parameters:

• chain_key (string, optional) — durable chain key
• agent_id (string, required) — stable agent id to disable

Returns: the updated agent record with status set to revoked.

mentisdb_skill_manifest

Return the versioned skill-registry manifest describing searchable fields and supported formats. Use this to discover which filter dimensions and format options are available before constructing skill search queries.

mentisdb_skill_manifest()

Parameters: none.

Returns: a manifest object listing searchable field names, supported export formats (markdown, json), and the current schema version.

mentisdb_head

Return head metadata for a MentisDB chain including chain length, the latest thought at the tip, and the head hash. Use this for a lightweight chain status check without loading any thoughts.

mentisdb_head(
chain_key: "my-project"     // optional
)

Parameters:

• chain_key (string, optional) — durable chain key

Returns: { thought_count, head_hash, tip } where tip is the latest thought object (or null if the chain is empty).

mentisdb_merge_chains

Merge all thoughts from a source chain into a target chain, then permanently delete the source chain. Agent identities are remapped autonomously: each source agent is matched to the closest existing target agent by character-set similarity (Jaccard). No new agents are created on the target chain. Cross-chain thought refs are dropped (they are chain-local indices).

mentisdb_merge_chains(
source_chain_key: "old-project",    // required — will be deleted
target_chain_key: "unified-project"  // required — must already exist
)

Parameters:

• source_chain_key (string, required) — chain key to merge from (deleted after success)
• target_chain_key (string, required) — chain key to merge into (must already exist)

Returns: { thoughts_copied, agents_remapped, source_deleted }.