Metadata-Version: 2.4
Name: mudra
Version: 0.4.1
Summary: Your identity, sealed and portable across every AI agent
Project-URL: Homepage, https://github.com/Mathews-Tom/mudra
Project-URL: Repository, https://github.com/Mathews-Tom/mudra
Project-URL: Issues, https://github.com/Mathews-Tom/mudra/issues
Project-URL: Changelog, https://github.com/Mathews-Tom/mudra/blob/main/CHANGELOG.md
Author: Mathews-Tom
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: click<9,>=8.0
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: tomli-w>=1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.5; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: interview
Requires-Dist: litellm>=1.0; extra == 'interview'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.25; extra == 'mcp'
Description-Content-Type: text/markdown

# 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](https://modelcontextprotocol.io/) 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`):

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

**Cursor** (`.cursor/mcp.json`):

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

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

```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](https://github.com/BerriAI/litellm). Configure defaults in `.mudra/config.toml`:

```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`:

```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](https://github.com/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
