{"_id":"@brainsparker/you-md","_rev":"2-116944b0f96e12e9dd1917c769b193ec","name":"@brainsparker/you-md","dist-tags":{"latest":"0.2.1"},"versions":{"0.2.0":{"name":"@brainsparker/you-md","version":"0.2.0","keywords":["ai","mcp","cursor","claude","claude-code","windsurf","preferences","context","skill","developer-tools","ai-tools","you.md"],"author":{"name":"sparker"},"license":"MIT","_id":"@brainsparker/you-md@0.2.0","maintainers":[{"name":"brainsparker","email":"brianjsparker@gmail.com"}],"homepage":"https://github.com/brainsparker/you.md#readme","bugs":{"url":"https://github.com/brainsparker/you.md/issues"},"bin":{"you-md":"bin/you-md.js","you-md-mcp":"bin/you-md-mcp.js"},"dist":{"shasum":"c50f67a98bdabd9de4ffd2d3c52f9022a0312160","tarball":"https://registry.npmjs.org/@brainsparker/you-md/-/you-md-0.2.0.tgz","fileCount":23,"integrity":"sha512-QQ1LA5evqIG2UHod1Fnr0eXEvJvNtd4zkI9HUxLct0AC3BewHS55eCkWqBmhO4/0879PcTBwJpevVh2YhVLHlA==","signatures":[{"sig":"MEYCIQDbF8mxvbzluKuejPY8FSgkPNP9ZtRYnGlFqhG1ZENRrQIhAPrJSgzURldf/GXq2s8Wp26AjFHiltXufZJ4dNeR9DgN","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1307288},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./mcp":{"types":"./dist/mcp.d.ts","import":"./dist/mcp.mjs","require":"./dist/mcp.js"}},"gitHead":"8091cf1347f3e3b420ac20eaaf9275148a221676","scripts":{"dev":"tsup --watch","eval":"npm run eval:search && npm run eval:agent","lint":"tsc --noEmit","test":"vitest run","build":"tsup","eval:agent":"npx tsx eval/agent_eval.ts","test:watch":"vitest","eval:search":"npx tsx eval/search_eval.ts","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm run test"},"_npmUser":{"name":"brainsparker","email":"brianjsparker@gmail.com"},"repository":{"url":"git+https://github.com/brainsparker/you.md.git","type":"git"},"_npmVersion":"11.12.1","description":"A skill that makes every AI tool know you — portable preferences and context across Claude Code, Cursor, Windsurf, and more","directories":{},"_nodeVersion":"25.9.0","dependencies":{"prompts":"^2.4.2","@modelcontextprotocol/sdk":"^1.25.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","tsup":"^8.5.0","vitest":"^2.1.0","typescript":"^5.7.0","@types/node":"^25.0.3","@types/prompts":"^2.4.9","@anthropic-ai/sdk":"^0.71.2","@vitest/coverage-v8":"^2.1.0"},"_npmOperationalInternal":{"tmp":"tmp/you-md_0.2.0_1786630878979_0.8981582748018","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@brainsparker/you-md","version":"0.2.1","description":"A skill that makes every AI tool know you — portable preferences and context across Claude Code, Cursor, Windsurf, and more","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","bin":{"you-md":"bin/you-md.js","you-md-mcp":"bin/you-md-mcp.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./mcp":{"types":"./dist/mcp.d.ts","import":"./dist/mcp.mjs","require":"./dist/mcp.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"tsc --noEmit","prepublishOnly":"npm run build && npm run test","eval:search":"npx tsx eval/search_eval.ts","eval:agent":"npx tsx eval/agent_eval.ts","eval":"npm run eval:search && npm run eval:agent"},"keywords":["ai","mcp","cursor","claude","claude-code","windsurf","preferences","context","skill","developer-tools","ai-tools","you.md"],"author":{"name":"sparker"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/brainsparker/you.md.git"},"bugs":{"url":"https://github.com/brainsparker/you.md/issues"},"homepage":"https://github.com/brainsparker/you.md#readme","devDependencies":{"@anthropic-ai/sdk":"^0.71.2","@types/node":"^25.0.3","@types/prompts":"^2.4.9","@vitest/coverage-v8":"^2.1.0","tsup":"^8.5.0","tsx":"^4.21.0","typescript":"^5.7.0","vitest":"^2.1.0"},"engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.25.1","prompts":"^2.4.2"},"publishConfig":{"access":"public"},"gitHead":"76ac9e30683fe0e642cc61922bb87b8bb21e9bea","_id":"@brainsparker/you-md@0.2.1","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-/KHJnsF777U1l7z8a9L/zsgaya7FR9/QdwITmH/GUviseW2Mo1dSvCie4Ue5hkbkkAUILFpeM0xp4e5pLdL6xQ==","shasum":"7ec12fe6c1a8d39e2ea6a11f7680fe6d0c5afa0e","tarball":"https://registry.npmjs.org/@brainsparker/you-md/-/you-md-0.2.1.tgz","fileCount":23,"unpackedSize":1412300,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFWrmrQU2iLY6S2JHQS5M31hbWyWr+hNAqOjR1edfyBVAiEA4YRN8Km6qs5GuvZEzwhsViAAPe05Qbsu7NCUj3F28hI="}]},"_npmUser":{"name":"brainsparker","email":"brianjsparker@gmail.com"},"directories":{},"maintainers":[{"name":"brainsparker","email":"brianjsparker@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/you-md_0.2.1_1786633863703_0.6138566244338435"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-13T14:21:18.721Z","modified":"2026-08-13T15:11:04.001Z","0.2.0":"2026-08-13T14:21:19.175Z","0.2.1":"2026-08-13T15:11:03.846Z"},"bugs":{"url":"https://github.com/brainsparker/you.md/issues"},"author":{"name":"sparker"},"license":"MIT","homepage":"https://github.com/brainsparker/you.md#readme","keywords":["ai","mcp","cursor","claude","claude-code","windsurf","preferences","context","skill","developer-tools","ai-tools","you.md"],"repository":{"type":"git","url":"git+https://github.com/brainsparker/you.md.git"},"description":"A skill that makes every AI tool know you — portable preferences and context across Claude Code, Cursor, Windsurf, and more","maintainers":[{"name":"brainsparker","email":"brianjsparker@gmail.com"}],"readme":"# you.md\n\n**Who you are. What you've lived. What you're becoming.**\n\nEvery AI tool you open starts from zero. It doesn't know how you think, what you've built, or where you're headed. You re-explain yourself every session, every tool, every project.\n\nyou.md fixes that. Define yourself once in a simple markdown file. Install the skill. Every AI tool you use — Cursor, Claude Code, Windsurf, and more — now knows exactly who you are and how you work.\n\n```bash\n# Install the CLI, then wire the skill into all your AI tools\nnpm install -g @brainsparker/you-md\nyou-md skill install\n```\n\nThat's it. No manual JSON editing. No per-tool setup. The skill auto-detects every supported tool you have installed and wires itself in.\n\n> **Package name:** install `@brainsparker/you-md` (the CLI commands are still `you-md` and `you-md-mcp`). The unscoped `youmd` package on npm is an unrelated project by a different author.\n\n---\n\n## Quick Start\n\nInstall once: `npm install -g @brainsparker/you-md` (or prefix any command below with `npx -y -p @brainsparker/you-md`).\n\n### 1. Create your you.md profile\n\n```bash\nyou-md init -i    # Interactive wizard (recommended)\n```\n\n### 2. Install the skill\n\n```bash\nyou-md skill install\n```\n\nThis auto-detects and configures: **Claude Code**, **Claude Desktop**, **Cursor**, and **Windsurf**.\n\nRestart your AI tools. They now know you.\n\n### 3. Check your status\n\n```bash\nyou-md skill status\n```\n\n---\n\n## What the skill does\n\nOnce installed, every supported AI tool gets access to:\n\n- Your coding language and framework preferences\n- Your naming conventions and code style\n- Your communication preferences (concise vs. verbose, emoji use, etc.)\n- Your role and professional context\n- Project-level overrides (`.you.md` in your project root overrides `~/.you.md`)\n\nThe skill works via [MCP (Model Context Protocol)](https://modelcontextprotocol.io) and exposes three tools your AI can call:\n\n| Tool | What it does |\n|---|---|\n| `youmd_get_preferences` | Returns your full preferences for context injection |\n| `youmd_summarize` | One-paragraph summary of who you are — fast context for new sessions |\n| `youmd_tool_config` | Generates tool-specific config (Cursor rules, Claude instructions) from your profile |\n\n---\n\n## Manual installation (advanced)\n\nIf you prefer to configure tools manually, add this to your tool's MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"you-md\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"@brainsparker/you-md\", \"you-md-mcp\"]\n    }\n  }\n}\n```\n\nConfig file locations:\n- **Claude Code:** `~/.claude/claude_desktop_config.json`\n- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Cursor:** `~/.cursor/mcp.json`\n- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`\n\n---\n\n## CLI Reference\n\n```bash\n# Skill management\nyou-md skill install              Install into all detected AI tools\nyou-md skill install cursor       Install into a specific tool only\nyou-md skill status               Show which tools have the skill active\nyou-md skill uninstall            Remove from all tools\n\n# Profile management\nyou-md init -i                    Interactive wizard (recommended)\n\n# Create a new you.md file\nyou-md init\n\n# Create in a specific location\nyou-md init ~/.you.md\n\n# Validate a you.md file\nyou-md validate .you.md\n\n# Merge user and project profiles\nyou-md merge ~/.you.md ./.you.md -o merged.md\n\n# Convert from .cursorrules\nyou-md convert .cursorrules -o .you.md\n\n# Export your preferences into each tool's native instruction file\nyou-md export --all               Export to every supported tool\nyou-md export claude gemini       Export to specific tools\nyou-md export --all --dry-run     Preview without writing\n```\n\n### Library Usage\n\n```typescript\nimport { createParser } from \"@brainsparker/you-md\";\n\nconst parser = createParser();\n\n// Parse content directly\nconst result = parser.parse(`---\nschema_version: \"1.0\"\nauthor: \"Developer\"\n---\n\n# Technical Preferences\n\nLanguage: TypeScript\nFramework: React\n`);\n\nconsole.log(result.profile.metadata.author); // \"Developer\"\nconsole.log(result.profile.sections.get(\"technical preferences\"));\n\n// Load from file\nconst fileResult = await parser.loadFromPath(\"./.you.md\");\n\n// Auto-discover you.md (checks ./.you.md, ~/.you.md, etc.)\nconst discovered = await parser.discover();\n\n// Merge profiles (project overrides user)\nconst userProfile = await parser.loadFromPath(\"~/.you.md\");\nconst projectProfile = await parser.loadFromPath(\"./.you.md\");\nconst merged = parser.merge([userProfile.profile, projectProfile.profile]);\n\n// Validate\nconst validation = parser.validate(merged);\nconsole.log(validation.valid, validation.errors, validation.warnings);\n```\n\n## you.md File Format\n\n### Identity Format (Default, v1.1)\n\nHuman-centric format for everyone:\n\n```markdown\n---\nschema_version: \"1.1\"\ncreated: \"2025-01-13\"\nprivacy_level: \"private\"\n---\n\n# Me\n\n## How I Think\n\nExpertise: expert\nLearning style: hands-on\nDecision making: data-driven\nDepth preference: thorough\n\n## How I Communicate\n\nVerbosity: concise\nTone: direct\nExplanations: only when asked\nExamples: yes, when helpful\n\n## What I Trust\n\nTrusted sources: official documentation, peer-reviewed\nFact-checking: strict\nContent warnings: standard\nSource quality: high\n\n## What I'm Into\n\nTopics: distributed systems, machine learning\nContent depth: long-form analysis\nVisual content: minimal\n\n## Where I'm Headed\n\nCurrently exploring: Rust for systems programming\nBuilding toward: distributed systems consultancy\nLearning: category theory, formal verification\n\n## Context\n\nLanguage: en-US\nTimezone: America/Los_Angeles\n\n## Don't\n\n- Over-explain things I already know\n- Use excessive caveats or hedging\n- Assume I need hand-holding\n```\n\n### Developer Format\n\nFor developers who want coding-specific preferences:\n\n```bash\nyou-md init --format developer\n```\n\n```markdown\n---\nschema_version: \"1.0\"\nprivacy_level: \"private\"\n---\n\n# you.md\n\n## Technical Preferences\n\nPrimary Languages: TypeScript, Python\nFrameworks: FastAPI, React\n\n## Communication Style\n\nVerbosity: concise\nExplanations: when_asked\nCode Comments: sparse\n\n## Code Generation Preferences\n\n- Include type annotations\n- Add error handling for I/O\n- Prefer dependency injection\n\n## Don't\n\n- Add verbose explanations unless asked\n- Suggest obvious refactors\n```\n\n## Discovery Order\n\nThe parser discovers you.md files in this order (first found wins):\n\n1. **Explicit path** - `--you-md <path>` or `YOU_MD_PATH` env var\n2. **Project-local** - `./.you.md` or `./you.md`\n3. **User home** - `~/.you.md`\n4. **XDG config** - `~/.config/you.md` or `~/.config/you/you.md`\n5. **Remote URL** - If enabled via options\n\n## CLI Commands\n\n### `you-md init [path]`\n\nCreate a new you.md file with a template.\n\n```bash\nyou-md init -i                     # Interactive wizard (easiest!)\nyou-md init                        # Creates ./.you.md (identity template)\nyou-md init ~/.you.md              # Creates global profile\nyou-md init --format identity      # Human-centric identity (default)\nyou-md init --format developer     # Developer-focused coding preferences\nyou-md init --format signals       # Full personalization signals\nyou-md init --format minimal       # Quick start minimal template\nyou-md init --force                # Overwrite existing\n```\n\nThe interactive wizard (`-i`) asks a few questions and generates your profile - no manual editing needed.\n\n### `you-md validate <path>`\n\nValidate a you.md file against the schema.\n\n```bash\nyou-md validate .you.md\nyou-md validate .you.md --json     # Output as JSON\nyou-md validate .you.md --verbose  # Show details\n```\n\n### `you-md merge <files...>`\n\nMerge multiple you.md files. Later files override earlier ones.\n\n```bash\nyou-md merge ~/.you.md ./.you.md             # Output to stdout\nyou-md merge ~/.you.md ./.you.md -o out.md   # Output to file\nyou-md merge a.md b.md c.md --json           # Output as JSON\n```\n\n### `you-md convert <input>`\n\nConvert from other formats to you.md.\n\n```bash\nyou-md convert .cursorrules              # Output to stdout\nyou-md convert .cursorrules -o .you.md   # Output to file\n```\n\n### `you-md export [targets...]`\n\nWrite your you.md preferences into each tool's native instruction file. This is the\noutbound counterpart to `convert`: tools that don't speak MCP (or that you haven't\nwired the skill into) still get your preferences, because they already read these\nfiles at session start.\n\n```bash\nyou-md export --all                # Export to every supported tool\nyou-md export claude gemini        # Export to specific tools\nyou-md export --all --dry-run      # Preview paths and actions, write nothing\nyou-md export claude -o ./out.md   # Override the output path (single target)\n```\n\nSupported targets:\n\n| Target     | Tool               | File written                                   |\n| ---------- | ------------------ | ---------------------------------------------- |\n| `claude`   | Claude Code        | `~/.claude/CLAUDE.md`                          |\n| `codex`    | Codex CLI          | `~/.codex/AGENTS.md`                           |\n| `gemini`   | Gemini CLI         | `~/.gemini/GEMINI.md`                          |\n| `windsurf` | Windsurf           | `~/.codeium/windsurf/memories/global_rules.md` |\n| `cursor`   | Cursor             | `./.cursor/rules/you-md.mdc`                   |\n| `agents`   | Any AGENTS.md tool | `./AGENTS.md`                                  |\n\nExports are idempotent. Managed content lives between `<!-- you-md:begin -->` and\n`<!-- you-md:end -->` markers, so anything else you keep in those files is preserved,\nand re-running `you-md export` updates the block in place. Existing files are backed\nup to `<file>.backup` before each write. The `cursor` target is the exception: it\nwrites a dedicated `you-md.mdc` rule file that you-md owns entirely.\n\n## API Reference\n\n### `createParser(options?)`\n\nCreate a new parser instance.\n\n```typescript\nconst parser = createParser({\n  maxFileSize: 100 * 1024, // 100KB default\n});\n```\n\n### `parser.parse(content, options?)`\n\nParse a you.md string.\n\n```typescript\nconst result = parser.parse(content);\n// result.success: boolean\n// result.profile: YouMdProfile\n// result.errors: ParseError[]\n// result.warnings: ParseWarning[]\n```\n\n### `parser.loadFromPath(path, options?)`\n\nLoad and parse from filesystem.\n\n```typescript\nconst result = await parser.loadFromPath(\"./.you.md\");\n```\n\n### `parser.loadFromUrl(url, fetchOptions?, parseOptions?)`\n\nLoad and parse from HTTPS URL.\n\n```typescript\nconst result = await parser.loadFromUrl(\"https://example.com/you.md\");\n```\n\n### `parser.discover(options?)`\n\nAuto-discover and load you.md.\n\n```typescript\nconst result = await parser.discover({\n  cwd: process.cwd(),\n  envVar: \"YOU_MD_PATH\",\n  enableRemote: false,\n});\n```\n\n### `parser.merge(profiles, options?)`\n\nMerge multiple profiles.\n\n```typescript\nconst merged = parser.merge([userProfile, projectProfile], {\n  arrayMerge: \"replace\", // or \"concat\", \"unique\"\n});\n```\n\n### `parser.validate(profile)`\n\nValidate a profile.\n\n```typescript\nconst validation = parser.validate(profile);\n// validation.valid: boolean\n// validation.errors: ValidationError[]\n// validation.warnings: ValidationWarning[]\n```\n\n## Types\n\n```typescript\ninterface YouMdProfile {\n  schemaVersion: string;\n  metadata: ProfileMetadata;\n  sections: Map<string, YouMdSection>;\n  rawContent: string;\n  sourcePath?: string;\n}\n\ninterface ProfileMetadata {\n  schemaVersion: string;\n  created?: string;\n  lastUpdated?: string;\n  privacyLevel?: \"public\" | \"private\" | \"authenticated\";\n  author?: string;\n  tags?: string[];\n  // ... additional fields\n}\n\ninterface YouMdSection {\n  title: string;\n  normalizedTitle: string;\n  level: number;\n  content: string;\n  fields: Map<string, YouMdField>;\n  subsections: YouMdSection[];\n}\n```\n\n## Personalization Signals\n\nThe library supports extended personalization profiles for search and AI systems. These provide a machine-readable, human-inspectable control surface for AI agents and ranking systems.\n\n### Signal Categories\n\n| Category | Description |\n|----------|-------------|\n| Identity | Authentication state, trust scores, account age |\n| Location | Geographic context, timezone, regulatory region |\n| Language | Primary/secondary languages, reading level |\n| Device | Device type, OS, screen size, connection |\n| Search Behavior | Topics, search depth, reformulation patterns |\n| Content | Source preferences, expertise level, format bias |\n| AI Preferences | Verbosity, explanation depth, response format |\n| Trust & Safety | Misinformation sensitivity, content warnings |\n| Meta | Confidence scores, decay rates, experiments |\n\n### Creating a Personalization Profile\n\n```bash\nyou-md init --format signals ~/.personalization.md\n```\n\n### Extracting Signals\n\n```typescript\nimport { createParser, extractAllSignals, hasPersonalizationSignals } from \"you-md\";\n\nconst parser = createParser();\nconst result = await parser.loadFromPath(\"./personalization.md\");\n\nif (hasPersonalizationSignals(result.profile)) {\n  const signals = extractAllSignals(result.profile);\n\n  console.log(signals.identity?.trust_score);      // 0.92\n  console.log(signals.ai_preferences?.verbosity);  // \"concise\"\n  console.log(signals.content?.expertise_level);   // \"expert\"\n}\n```\n\n### Individual Signal Extraction\n\n```typescript\nimport {\n  extractIdentitySignals,\n  extractLocationSignals,\n  extractSearchBehaviorSignals,\n  extractAIPreferences,\n  getSignalCategories,\n} from \"you-md\";\n\n// Extract specific signal categories\nconst identity = extractIdentitySignals(profile);\nconst location = extractLocationSignals(profile);\nconst search = extractSearchBehaviorSignals(profile);\nconst ai = extractAIPreferences(profile);\n\n// Check which categories are present\nconst categories = getSignalCategories(profile);\n// [\"identity\", \"location\", \"language\", \"device\", \"search_behavior\", ...]\n```\n\n### Personalization Profile Format\n\n```markdown\n---\nschema_version: \"1.0\"\nprofile_type: \"personalization\"\ncreated: \"2025-01-09\"\n---\n\n# Personalization Profile\n\n## Identity\n\nlogged_in: true\ntrust_score: 0.92\nverified_level: email\nage_range: 25-34\n\n## Location\n\ncurrent_country: US\ntimezone: America/Los_Angeles\nregulatory_region: CCPA\n\n## Search Behavior\n\nrecent_topics: [\"distributed systems\", \"kubernetes\"]\nsearch_depth: deep\nexpertise_level: expert\n\n## AI Response Preferences\n\nverbosity: concise\nexplanation_depth: technical\ninclude_examples: true\ncode_comments: sparse\n\n## Trust and Safety\n\nmisinformation_sensitivity: high\nsource_reliability_threshold: 0.8\n```\n\n## MCP Server\n\nThe MCP server automatically loads your you.md preferences into Claude's context.\n\n### Setup\n\n1. Install: `npm install -g you-md`\n2. Add to Claude Code config (see Quick Start above)\n3. Create your profile: `you-md init ~/.you.md`\n4. Restart Claude Code\n\n### Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `youmd_get_preferences` | Get your merged preferences |\n| `youmd_init` | Create a new you.md file |\n| `youmd_validate` | Validate a you.md file |\n\n### Available Resources\n\n| URI | Description |\n|-----|-------------|\n| `youmd://preferences` | Your merged preferences (project + global) |\n| `youmd://project` | Project-level .you.md |\n| `youmd://global` | Global ~/.you.md |\n\n## Requirements\n\n- Node.js >= 18.0.0\n\n## License\n\nMIT\n","readmeFilename":"README.md"}