convez.ai
MCP ServerDevOps & InfraestruturaAvançado
mike-bronner

Workbench Core — Infraestrutura de Agente Persistente

mike-bronner/workbench-core

Camada de infraestrutura que adiciona persistência e identidade ao Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que transforma Claude Code em um agente colaborador persistente e consciente de identidade. Fornece infraestrutura para identidade persistente, guardrails comportamentais, logging de sessão, memória operacional integrada e gerenciamento automático de retenção de dados históricos.

Instalação

$npx convez-ai mike-bronner/workbench-core

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
25%
Último commit
há 1 dia
Versão
0.62.0
Issues abertas
9
Contribuidores
1

Casos de uso

  • Manter continuidade de identidade e conhecimento entre sessões de codificação
  • Implementar regras comportamentais imutáveis e auditáveis em agentes
  • Construir sistemas de memória operacional para projetos de longa duração
  • Criar trilhas de auditoria e histórico de decisões em workflows automatizados

Veredito

Plugin robusto para arquitetar agentes Claude com estado persistente e memória operacional. Exige familiaridade com MCP servers, shell scripting e infraestrutura de sessão, mas oferece foundation sólido para sistemas de IA autônomos em produção.

README

A tradução para o português deste README ainda está na fila.

core

Core infrastructure plugin for Claude Code. Part of the claude-workbench marketplace.

What this is

The infrastructure layer that turns Claude Code from a stateless coding assistant into a persistent, identity-aware collaborator. It provides:

  • Persistent identity — persona files (soul-hot.md, profile.md) injected at session start and re-injected after context compression so the agent never drifts.
  • Guardrails — absolute behavioral rules that ship with the plugin, load last (highest authority), and are enforced by the interview skills. Guardrails can't be overridden by persona or profile choices.
  • Session logging — every session is captured as a rolling JSONL log, then summarized by a background agent into a searchable narrative.
  • Operational memory — a local MCP server (markdown-vault-mcp) fronts a searchable vault of decisions, projects, insights, and session history.
  • Execution-aware skills — a behavioral protocol that gives any skill persistent memory via vault-backed learnings files.
  • Retention management — automatic cleanup of raw logs (28 days) and checkpoints (7 days); summaries and decisions persist indefinitely.

Installation

Prerequisites

Three things must be on your system before installing the plugin.

1. Claude Code CLI

Install from claude.ai/code.

2. jq — JSON parser used by the hook scripts

# macOS
brew install jq

# Debian / Ubuntu
sudo apt install jq

# Fedora / RHEL
sudo dnf install jq

3. markdown-vault-mcp — the MCP server backing the memory vault

You normally don't need to install this yourself — the plugin's launcher (hooks/mcp-memory.sh) self-installs the server from the fork on first run. All it needs is uv or pipx on your PATH (uv preferred). The plugin's .claude-plugin/plugin.json declares the memory MCP server and Claude Code auto-wires it on plugin install, so there's no claude mcp add step either. On a fresh machine the first MCP connection may hit Claude Code's 30s startup timeout while the install runs (~60–90s); the install completes in the background regardless, and the next session connects normally.

The launcher installs from the mikebronner/markdown-vault-mcp fork — the canonical source for this plugin. The fork carries index-state fixes the plugin relies on (persistent-index adoption at boot, offline-change reconciliation, tracker skip-state, embedding convergence, raw-transcript exclusion support) that are not yet in any PyPI release. They have been contributed upstream (pvliesdonk/markdown-vault-mcp#665); once an upstream release carries them, plain PyPI installs will work again — until then, installing from PyPI gets you a server that can exceed Claude Code's 30s MCP startup timeout on first boot.

If neither uv nor pipx is available, install one:

# uv — macOS:
brew install uv
# uv — Linux / other (via official installer):
curl -LsSf https://astral.sh/uv/install.sh | sh

# pipx — macOS:
brew install pipx
# pipx — Debian / Ubuntu:
sudo apt install pipx

Manual install / troubleshooting — if the bootstrap fails (the launcher logs mcp-memory:-prefixed errors to stderr), install the server yourself:

# Recommended — uv (fast, isolated, auto-manages Python version):
uv tool install --from git+https://github.com/mikebronner/markdown-vault-mcp markdown-vault-mcp --with fastmcp --with fastembed

# Alternative — pipx (isolated, no auto-Python-management):
pipx install git+https://github.com/mikebronner/markdown-vault-mcp

# Last resort — pip (global install, conflicts with system Python on modern
# macOS/Linux via PEP 668):
pip install --user git+https://github.com/mikebronner/markdown-vault-mcp

Verify:

markdown-vault-mcp --version

Install the plugin

/plugin marketplace add mike-bronner/claude-workbench
/plugin install workbench-core@claude-workbench

Optional: CLI system-prompt enforcement

Background: Claude Code's default system prompt includes rules like "no emojis unless asked" and specific tone/style directives. If your agent persona contradicts these (e.g., "use emojis liberally"), the system prompt wins — it's architecturally higher authority than CLAUDE.md or hook output, which are both delivered as user messages.

The plugin addresses this at three layers:

LayerFileAuthorityWorks in
1~/.claude/system-overrides.mdSystem prompt (highest)CLI only
2~/.claude/CLAUDE.md managed blockUser messageEverywhere
3SessionStart hook outputTool resultEverywhere

Layers 2 and 3 are automatic — the plugin generates and maintains them on every startup. Layer 1 requires a one-line shell alias because --append-system-prompt-file is CLI-only (no settings.json equivalent exists).

To activate Layer 1, add this to your shell profile (~/.zshrc, ~/.bashrc, etc.):

alias claude='claude --append-system-prompt-file ~/.claude/system-overrides.md'

Who needs this: Anyone using the Claude Code CLI whose agent persona overrides default system prompt behaviors (emoji usage, tone, sycophancy rules). If your persona doesn't contradict the defaults, Layers 2 and 3 are sufficient.

Who doesn't need this: Desktop app, web app (claude.ai/code), and IDE extension users — these don't go through the shell. For those environments, the plugin relies on Layers 2 and 3 as reinforcement. These work everywhere but can't architecturally override the system prompt.

Configure (required on first install)

The memory MCP server ships unconfigured. Run /workbench:customize on first install to set your paths:

SettingDescriptionDefault
agent_nameYour agent's name (e.g. Holmes)Claude
memory_pathWhere your operational memory lives on disk~/Documents/Claude/Memory
memory_cacheWhere indexes and checkpoints are stored~/.claude-memory-cache
memory_mcp_server_nameMCP server name for the vaultworkbench-memory
auto_summarizeSpawn background summary-writer on session endtrue
summary_modelModel for the background summary-writerhaiku

Configuration is stored in ~/.claude/plugins/data/workbench-core-claude-workbench/config.json and survives plugin updates. The MCP memory server is launched by hooks/mcp-memory.sh, which reads this file at launch time and exports the corresponding env vars — so a plugin version bump never clobbers your settings.

Set up identity files

There are three ways to get identity files in place — pick one:

Fastest — install a shipped persona. The plugin can ship ready-made personas under assets/personas/<name>/. Install one with:

/workbench-core:install-persona

It propagates the soul files to your vault, the output style to ~/.claude/output-styles/, and the outputStyle setting — and it's non-destructive: existing hand-edited soul files are diffed and confirmed before any overwrite. This is the quickest path to a durable voice, because the output style sits in the system prompt (which outranks context).

Guided — build from scratch via interview. Use /workbench-core:define-soul (below).

Manual — copy templates. The plugin expects identity files in your memory directory:

{memory_path}/identity/
├── soul-hot.md            — hard rules, voice constraints, drift test (loaded every session)
├── soul-core.md           — deep character, values, tensions (loaded on request)
├── profile.md             — user profile, preferences, working style (loaded every session)
└── skills-protocol.md     — execution-aware skills protocol (loaded every session)

Templates are provided in assets/templates/. Copy them to your memory directory and customize:

cp assets/templates/soul-hot.template.md ~/Documents/Claude/Memory/identity/soul-hot.md
cp assets/templates/soul-core.template.md ~/Documents/Claude/Memory/identity/soul-core.md
cp assets/templates/profile.template.md ~/Documents/Claude/Memory/identity/profile.md
cp assets/templates/skills-protocol.template.md ~/Documents/Claude/Memory/identity/skills-protocol.md

Replace {{agent_name}} placeholders with your agent's name, then edit to taste.

Alternatively, use the interactive skills to build these files through a guided interview:

  • /workbench:define-soul — walks through agent identity, voice, hard rules, and failure modes
  • /workbench:define-profile — walks through user role, working style, technical stack, privacy preferences, and session quality

These are the recommended approach — /workbench:customize will offer to launch them automatically on first install.

Execution-aware skills

Any skill execution reads a persistent learnings file before running. If the run produces a correction, an unexpected failure, or a confirmed non-obvious pattern, an entry is appended for next time. Files live at {memory_path}/skills/{skill-name}.learnings.md.

The protocol applies to any skill — workbench skills, third-party plugin skills, your own personal skills. No per-skill configuration needed.

The protocol is driven by {memory_path}/identity/skills-protocol.md, installed by /workbench:customize and loaded every session by the SessionStart hook (load order: soul-hot → profile → skills-protocol → guardrails). Remove the file if you want to disable the behavior; delete a specific skills/{skill-name}.learnings.md to reset one skill's accumulated state without touching the rest.

Compaction

When a learnings file exceeds 30 entries, the protocol flags it for compaction. /workbench:compact-learnings walks through each entry interactively:

  • Workbench plugin skills — learnings can be integrated directly into the SKILL.md (improving the skill definition) or kept/dropped
  • All other skills — learnings are compacted (kept, rewritten, or dropped) without touching the SKILL.md

Shared references

The references/ directory contains single-source-of-truth documents shared across skills and the summary-writer agent:

FileUsed byPurpose
guardrails.mdsession-warmup, define-soul, define-profileAbsolute behavioral rules — injected last at session start, enforced during interviews
summary-format.mdsummary-writer, log-now, summarize-sessionRequired frontmatter, body structure, JSONL parsing guidance
decision-promotion.mdsummary-writer, log-now, summarize-sessionPromotion criteria, when NOT to promote, decision file template
vault-conventions.mdsummary-writer, log-now, summarize-sessionVault paths, required frontmatter, write vs edit rules
linking-synthesis.mdsummary-writer, log-now, summarize-session, memory-lintWikilink syntax, related-document linking, topic-page synthesis, vault index contract

Most references are loaded at execution time via ${CLAUDE_PLUGIN_ROOT}/references/. The exception is guardrails.md, which is injected at every session start by the warmup hook.

Plugin layout

core/
├── .claude-plugin/
│   └── plugin.json              — manifest + MCP server config
├── agents/
│   └── summary-writer.md       — background narrative agent definition
├── assets/
│   ├── personas/              — optional ready-made personas (soul + output style)
│   └── templates/              — identity + protocol templates
├── hooks/
│   ├── hooks.json              — hook → script bindings
│   ├── session-log.sh          — raw log capture + summary-writer dispatch
│   └── session-warmup.sh       — identity injection + cleanup + health check
├── references/
│   ├── guardrails.md           — absolute behavioral rules (injected at session start)
│   ├── decision-promotion.md   — when and how to promote decisions
│   ├── linking-synthesis.md    — wikilinks, topic pages, vault index contract
│   ├── summary-format.md       — summary frontmatter + body template
│   └── vault-conventions.md    — paths, frontmatter rules, write conventions
├── skills/
│   ├── compact-learnings/      — review, compact, and integrate skill learnings
│   ├── customize/              — configure agent name, paths, MCP settings
│   ├── define-profile/         — interactive user profile interview
│   ├── define-soul/            — interactive agent identity onboarding
│   ├── install-persona/        — propagate a shipped persona to live locations
│   ├── log-now/                — dump + narrate the current session inline
│   ├── memory-lint/            — monthly vault health-and-repair pass
│   ├── process-pending-summaries/ — dispatch background agents for pending markers
│   └── summarize-session/      — manually summarize a specific session
├── scripts/
│   ├── install-chat-skills.sh  — package + install skills into Claude Chat
│   └── install-persona.sh      — propagate a shipped persona to live locations
└── README.md

How it works

Session lifecycle

Four hooks manage the session lifecycle:

HookScriptPurpose
SessionStarthooks/session-warmup.shIdentity injection, retention cleanup, MCP health check, pending-summary dispatch
PreCompacthooks/session-log.shDump raw log checkpoint, spawn summary-writer
PostCompacthooks/session-warmup.shRe-inject identity after context compression
SessionEndhooks/session-log.shDump final log segment, spawn summary-writer

Logging pipeline

Session event (PreCompact / SessionEnd / manual)
    ↓
hooks/session-log.sh
    ├── Load per-session checkpoint (where did I leave off?)
    ├── Extract new JSONL segment from transcript
    ├── Append to rolling log: sessions/YYYY-MM-DD/{session-id}.log.md
    ├── Update checkpoint
    ├── Write pending-summary marker
    └── Spawn background summary-writer (haiku, detached)
            ↓
        summary-writer agent
            ├── Read the rolling log
            ├── Write narrative .summary.md to vault
            ├── Promote decisions (if bar is met)
            ├── Update profile.md (if preferences shifted)
            └── Delete the marker

One rolling log file per session. Checkpoint and final segments are appended to the same file. The summary-writer spawns on every log write — later runs overwrite earlier summaries with the most complete picture.

Identity injection

Identity files are injected on every warmup source:

SourceWhenWhat happens
startupFresh sessionFull warmup: cleanup + health check + identity + pending summaries
resumeReconnectingIdentity refresh + pending summaries
clearAfter /clearIdentity refresh + pending summaries
compactAfter compressionIdentity refresh only (via PostCompact hook)

This ensures the agent never loses its voice or behavioral constraints, even in long sessions with multiple context compressions.

Guardrails

Identity files are customizable — users define their agent's persona via /workbench:define-soul and their own profile via /workbench:define-profile. But some rules should hold regardless of what persona is configured. That's the problem guardrails solve.

The problem: Without guardrails, the interview skills can produce identity files that encode bad habits — sycophantic openers, hedged opinions, unverified assertions. These are anti-patterns that degrade output quality no matter what character the agent plays. A user might accidentally request them ("soften critiques with a compliment first") without realizing they're undermining the agent's usefulness.

The solution: references/guardrails.md ships with the plugin as a set of absolute behavioral rules. They:

  1. Load last in the identity chain (after soul-hot, profile, skills-protocol) — giving them highest authority in context.
  2. Are enforced during interviews — both /workbench:define-soul and /workbench:define-profile check every answer against the guardrails. If an answer contradicts a guardrail, the skill stops, names the conflict, and recommends an alternative. It never suggests modifying the guardrails.
  3. Ship with the plugin, not the vault — guardrails are not user-configurable paths. They're plugin infrastructure, like the hook scripts.

The authority hierarchy for behavioral rules:

guardrails.md (absolute — ships with plugin)
    ↓ overrides
soul-hot.md (character-specific — user-defined)
    ↓ informs
profile.md (user context — user-defined)

Memory vault

The vault at {memory_path} is served by markdown-vault-mcp with:

  • FTS5 full-text search + FastEmbed local embeddings for hybrid search
  • Frontmatter indexing on: name, type, tags, summary, date, scope, log_files
  • Link graph — backlinks, outlinks, similar documents, connection paths
  • Incremental indexing — only reprocesses changed files
  • Transcript exclusion — raw sessions/**/*.log.md transcripts are excluded from indexing (write-only archival); they stay readable by path, and the indexed summaries carry log_files pointers to them

Vault structure:

{memory_path}/
├── identity/          — soul-hot, soul-core, profile, skills-protocol
├── decisions/         — architectural and process decisions
├── topics/            — topical synthesis pages (current state per theme)
├── projects/          — project context and system designs
├── insights/          — durable patterns and working principles
├── sessions/          — session logs (.log.md) and summaries (.summary.md)
│   └── YYYY-MM-DD/
├── skills/            — per-skill learnings files
├── infrastructure/    — systems and tools documentation
├── maintenance/       — memory-lint audit reports
├── index.md           — catalog of the curated layer (topics, decisions, identity, reference)
└── CLAUDE.md          — vault map (metadata only)

Canonical store & routing

The vault is the canonical durable memory store. Claude Code's harness also injects per-project memory instructions every session (save to ~/.claude/projects/<encoded-cwd>/memory/ + a MEMORY.md index) — left alone, sessions scatter memory files there that the vault can't search. The session warmup neutralizes that channel into a router: it injects a ## Memory routing rule at every session start (saves go to the vault via the memory MCP write tool with vault frontmatter; recall is vault hybrid search, not directory reads), and on startup it writes a self-healing router stub to the current project's MEMORY.md (canonical template: references/memory-routing-stub.md). A MEMORY.md without the router marker is never overwritten — the warmup flags it for human migration instead. Keep the store singular: don't install competing memory MCP servers alongside the vault.

Wiki layer and vault index

Session summaries are chronological sediment; left alone they accumulate as unlinked orphans. Every ingest path (the summary-writer agent, /workbench:log-now, /workbench:summarize-session) therefore follows references/linking-synthesis.md: search the vault for related decisions, topics, and prior summaries; add a ## Related section of path-qualified wikilinks ([[folder/file-stem|display text]] — the form markdown-vault-mcp resolves immediately); maintain at most one topical synthesis page in topics/ per session; and cross-link promoted decisions to their summaries and topics. Linking is deliberately conservative — only high-confidence connections, capped per ingest, because an orphan beats a forced link.

index.md at the vault root is the catalog of the curated layer — one wikilink + one-line hook per topic, decision, identity, and reference document (never sessions). It's the orientation entry point: agents read it on demand to get the lay of the vault before searching — it is not auto-loaded into context. The summary writers keep it current as they create topics and promote decisions; the lint ritual repairs drift.

Lint ritual

Vaults rot silently: files written without the required name/type frontmatter are skipped at index time (on disk but invisible to search), links break when targets move, orphans accumulate. /workbench-core:memory-lint is the periodic repair pass — it diffs the filesystem against the index to find skipped files and rescues their frontmatter, repairs or removes broken links, adds only high-confidence links (never mass-links orphans), repairs index.md drift in both directions (missing entries for topics/ and decisions/ documents, stale entries pointing at deleted ones), and flags duplicates/contradictions for the human instead of merging. Each run is capped at 50 file-fixes and writes an audit report to maintenance/ with before/after stats. Intended cadence: monthly, deployed via the scheduled-tasks MCP. Raw *.log.md transcripts are never touched.

Retention

Runs on every startup warmup:

ArtifactRetentionRationale
Raw .log.md files7 daysSummaries are the durable record
Checkpoint files7 daysSessions don't resume after that
Legacy summary-writer logsImmediate cleanupNo longer generated; remnants deleted on startup
Summary .summary.md filesForeverSearchable session history
Decisions, identity, projectsForeverCore operational memory

Skills

SkillDescription
/workbench:customizeConfigure agent name, paths, summary model, identity files
/workbench:define-soulInteractive onboarding/refinement for agent identity (soul-hot, soul-core)
/workbench-core:install-personaInstall a shipped persona — soul files + output style + outputStyle setting — into your live locations; non-destructive
/workbench:define-profileInteractive interview to build/refine the user's profile.md (role, working style, stack, privacy, session quality)
/workbench:log-nowDump the current session log and write a narrative summary inline
/workbench:summarize-sessionManually summarize a specific session (or pick from unsummarized)
/workbench:process-pending-summariesDispatch background agents to clear pending summary markers
/workbench:compact-learningsReview and compact accumulated skill learnings; integrate into SKILL.md for workbench skills
/workbench-core:memory-lintMonthly health-and-repair pass over the memory vault — frontmatter rescue, broken-link repair, conservative orphan linking, vault-index drift repair, duplicate flagging, audit report
/workbench-core:install-chat-skillsDiscover skills in @claude-workbench plugins and install them into the Claude Mac app's Chat surface via .skill packaging

All skills are execution-aware — they check for a skills/{name}.learnings.md file in the vault before running and apply any accumulated learnings from prior executions.

Cross-surface skill installation

workbench-core auto-discovers installable skills in dependent @claude-workbench plugins and surfaces a notice in the SessionStart warmup output when new or updated skills are available:

## 📦 New Chat-installable skills

The following skills can be installed into Claude Chat (Mac app):
- `develop` (from `workbench-dev-team`)
- `git-commit` (from `workbench-dev-team`)

Click to install: `/workbench-core:install-chat-skills`

The detection runs once per session start (source: startup only) and uses a state-file mtime fast-path — when nothing has changed since the last run, the check is a single stat. The cold path triggers only after claude plugin install/update actually changes installed_plugins.json.

The slash command (/workbench-core:install-chat-skills) packages each eligible skill via skill-creator's package_skill.py, opens the resulting .skill files with the Mac app, and updates ~/.claude-workbench/chat-skills-state.json so the notice clears. Requires the skill-creator@claude-plugins-official plugin (the script will tell you to install it if missing).

The notice persists until the user installs — if you ignore it once, it'll appear again on the next session start. Skipping a skill in the install dialog has the same effect.

Environment variable overrides

All config values can be overridden via environment variables for testing:

VariableOverrides
WORKBENCH_AGENT_NAMEagent_name
WORKBENCH_MEMORY_PATHmemory_path
WORKBENCH_MEMORY_CACHEmemory_cache
WORKBENCH_SUMMARY_MODELsummary_model
WORKBENCH_AUTO_SUMMARIZEauto_summarize
WORKBENCH_LOG_MODEForce log mode (checkpoint, final, manual)
WORKBENCH_SKIP_LOGSet to 1 to skip logging (used by summary-writer)
WORKBENCH_SKIP_WARMUPSet to 1 to skip warmup (used by summary-writer)
WORKBENCH_MCP_SERVER_NAMEmemory_mcp_server_name
WORKBENCH_SETTINGS_FILE~/.claude/settings.json path (used by install-persona tests)
WORKBENCH_OUTPUT_STYLES_DIR~/.claude/output-styles path (used by install-persona tests)

Known limitations

  • Restart after plugin update. CLAUDE_PLUGIN_ROOT is resolved once at session startup. After updating, restart Claude Code to pick up changes.
  • Summary-writer race on rapid compactions. If a session compacts multiple times in quick succession, multiple summary-writers may run concurrently. The last one wins (overwrites the summary), which is always the most complete — but intermediate writers do wasted work.

Design philosophy

The plugin is infrastructure first, persona optional. Your agent's personality comes from the identity files you customize — the framework imposes none. Templates in assets/templates/ use {{agent_name}} placeholders. The plugin may also ship ready-made personas under assets/personas/<name>/ (soul files + output style) as optional starting points: you opt in via /workbench-core:install-persona, which copies them to your editable locations — they are never enforced, and the framework stays generic for anyone who wants to start from blank templates. The one thing that isn't optional is references/guardrails.md — universal quality constraints (no sycophancy, no hedging, verify before asserting), not personality.

Memory files live outside any git repo, at a user-configured path. Memory is personal state; the plugin is code. They are intentionally separate.

Ver o original no GitHub

Bom para

Relacionados