mudra 0.4.1

Your identity, sealed and portable across every AI agent

Mudra

Your identity, sealed and portable across every AI agent.

mudra (मुद्रा) (/ˈmuːdrə/): a seal, stamp, or mark of identity — a personal imprint that authenticates who you are.

Mudra is a CLI tool and MCP server that lets you build, manage, and serve a structured personal context portfolio to any AI agent. It replaces the repetitive process of re-explaining yourself to every new AI session with a single, portable, machine-readable identity layer.

The Problem

Every AI interaction starts at zero. You re-explain your role, preferences, constraints, communication style, and project context to each new agent, each new session, each new tool. With one agent, it's tolerable. With three, it's friction. With ten — the direction we're all headed — it's untenable.

Platform-native solutions (ChatGPT Memory, Claude Projects) lock context inside one vendor. When you switch tools or use multiple tools simultaneously, you start from scratch.

How It Works

$ uv tool install mudra

$ mudra init                           # Create portfolio with 4 core files
$ mudra edit identity                  # Open in $EDITOR with guided template
$ mudra serve                          # Start MCP server — agents pull context on demand
$ mudra status                         # Check freshness and completeness

Your portfolio lives in ~/.mudra/ as plain markdown files, git-versioned automatically. Agents connect via MCP and receive only the context relevant to their role.

Portfolio Files

Core Files (created on init)

File	What It Captures
identity.md	Name, role, org, what you do
tools-and-systems.md	Tech stack, integrations, rejected tools
communication-style.md	Tone, formatting, dislikes, voice
preferences-and-constraints.md	Hard rules — always/never constraints

Extended Files (added on demand)

File	What It Captures
role-and-responsibilities.md	Work rhythms, deliverables, reporting structure
current-projects.md	Active workstreams, status, collaborators
team-and-relationships.md	Key people, interaction patterns, dependencies
goals-and-priorities.md	What you're optimizing for at every time horizon
domain-knowledge.md	Areas of expertise, terminology, knowledge gaps
decision-log.jsonl	Past decisions and their reasoning (structured, append-only)

Start with 4 core files (~15 minutes of writing). Add extended files when you feel the absence.

$ mudra add current-projects           # Add an extended file when you need it
$ mudra add domain-knowledge

Selective Context Routing

Not every agent needs all your files. Mudra maps agent roles to file subsets:

Role	Files Served
general-assistant	identity + communication-style + preferences
code-review	identity + communication-style + tools + preferences
meeting-prep	identity + team + current-projects + goals
writing-assistant	identity + communication-style + domain-knowledge
strategic-advisor	identity + goals + projects + decision-log + preferences
career-coach	identity + role + goals + domain-knowledge + decision-log
full	all files

Extended files that haven't been added are silently skipped — no errors, no empty placeholders.

MCP Server

Connect any MCP-compatible agent to your portfolio:

$ mudra serve                          # stdio transport (default)
$ mudra serve --transport streamable-http --port 3100

Client Configuration

Claude Code (~/.claude.json or .mcp.json):

{
  "mcpServers": {
    "mudra": {
      "command": "mudra",
      "args": ["serve"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "mudra": {
      "command": "mudra",
      "args": ["serve"]
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "mudra": {
      "command": "mudra",
      "args": ["serve"]
    }
  }
}

MCP Resources

The server exposes four resource URIs:

URI	Description
mudra://portfolio/{file_name}	Single file read
mudra://portfolio/role/{role_name}	Role-based context (selective routing)
mudra://portfolio/all	All existing files combined
mudra://portfolio/status	Freshness report

Export

For platforms without MCP support, export your portfolio in four formats:

$ mudra export --format system-prompt              # <user_context> XML wrapper
$ mudra export --format markdown                   # Concatenated markdown
$ mudra export --format api-payload                # JSON with metadata
$ mudra export --format claude-project --output ./export  # Individual files in directory

Role filtering works with export too:

$ mudra export --format system-prompt --role code-review

Interview Engine

Prefer guided creation over manual writing? The interview engine conducts structured Q&A and synthesizes your answers into polished portfolio files:

$ mudra interview --file identity
$ mudra interview --file tools-and-systems --provider openai

Supports Anthropic, OpenAI, and Ollama via litellm. Configure defaults in .mudra/config.toml:

[interview]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
temperature = 0.3
max_questions_per_file = 8

Interrupted interviews can be resumed:

$ mudra interview --file identity --resume

Community Templates

Start from a role-specific template instead of blank files:

$ mudra templates                      # List available templates
$ mudra init --template engineer       # Initialize with pre-filled content
$ mudra init --template manager
$ mudra init --template designer

Templates include real, customizable content for each role — not empty placeholders.

Freshness Tracking

Mudra tracks when each file was last updated and warns when content goes stale:

$ mudra status                         # Freshness report
$ mudra validate                       # Health checks with severity levels
$ mudra validate --strict              # Treat warnings as errors (for CI)

Default staleness thresholds:

File	Threshold
identity	90 days
tools-and-systems	60 days
communication-style	90 days
preferences-and-constraints	60 days
current-projects	21 days
team-and-relationships	30 days
goals-and-priorities	30 days
domain-knowledge	90 days

Decision Log

Track decisions with structured entries:

$ mudra log "Chose Click over Typer" --context "Typer magic inference conflicts with explicit style" --tags tooling,architecture
$ mudra log --list                     # View recent decisions
$ mudra log --list --tag architecture  # Filter by tag

Git-Backed Version History

Every edit is a git commit. Full diff history, painless reverts, clear audit trail:

$ mudra history                        # View commit log
$ mudra history --file identity        # Filter to one file
$ mudra history --diff                 # Show diffs

Multiple Profiles

Maintain separate contexts for different roles:

$ mudra init --profile work
$ mudra init --profile personal
$ mudra edit identity --profile work
$ mudra serve --profile work

Installation

Requires Python 3.12+.

$ uv tool install mudra                # Recommended
$ pip install mudra                    # Alternative

With optional extras:

$ uv tool install "mudra[mcp]"         # MCP server support
$ uv tool install "mudra[interview]"   # Interview engine (requires LLM API key)

Configuration

Configuration lives in .mudra/config.toml:

[portfolio]
path = "~/.mudra"
version = "1"

[freshness]
check_on_serve = true
default_staleness_days = 30

[freshness.thresholds]
identity = 90
tools-and-systems = 60
current-projects = 21

[mcp]
transport = "stdio"
port = 3100

[interview]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
temperature = 0.3
max_questions_per_file = 8

Read and write config values:

$ mudra config get freshness.default_staleness_days
$ mudra config set mcp.port 8080

CLI Reference

Command	Description
mudra init [--template NAME]	Initialize a new portfolio
mudra edit <file>	Edit a file in $EDITOR
mudra add <file>	Add an extended file
mudra status [--json]	Freshness and completeness report
mudra validate [--strict] [--file NAME]	Health checks
mudra history [--file NAME] [--diff]	Git history
mudra roles [--verbose]	List routing roles
mudra config get <key>	Read config value
mudra config set <key> <value>	Write config value
mudra log <text> [--context --tags]	Append to decision log
mudra log --list [--tag TAG]	View decisions
mudra export --format FMT [--role --output]	Export portfolio
mudra serve [--transport --port]	Start MCP server
mudra interview --file NAME [--provider --resume]	Guided Q&A creation
mudra templates	List community templates

Prior Art

The concept of a structured personal context portfolio in markdown files was published by nlwhittemore/personal-context-portfolio. Mudra builds tooling on top of this idea — the foundational concept is not novel to this project. The delta is in the serving infrastructure (MCP), selective routing, freshness management, interview engine, and the core/extended tier system.

License

MIT