{
  "markdown": "# 🏠 tilde\n\n> *Your AI agents' home directory*\n\n**tilde** is a privacy-first [Model Context Protocol](https://registry.modelcontextprotocol.io) (MCP) server that acts as the universal memory and profile layer for AI Agents.\n\nConfigure once. Use everywhere. Your data, your control.\n\nSupports profile management, skills, resume import, and team sync.\n---\n\n## The Problem\n\nEvery time you switch AI tools, you face the same issues:\n\n- **🔄 Repetition**: \"I'm a Senior SWE\", \"I prefer Python\", \"Don't use ORMs\"\n- **🧩 Fragmentation**: Preferences learned in Cursor aren't available in Claude\n- **🔒 Privacy Concerns**: Unsure who has access to your personal context\n\n## The Solution\n\n**tilde** acts as a \"digital passport\" that your AI agents can read:\n\n```\n┌────────────────────────────────────────────────────────────┐\n│  Claude Desktop  │   Cursor   │  Windsurf  │  Your Agent   │\n└────────┬─────────┴─────┬──────┴─────┬──────┴───────┬───────┘\n         │               │            │              │\n         └───────────────┴─────┬──────┴──────────────┘\n                               │\n                    ┌──────────▼──────────┐\n                    │   tilde MCP Server  │\n                    │   (runs locally)    │\n                    └──────────┬──────────┘\n                               │\n                    ┌──────────▼──────────┐\n                    │   ~/.tilde/profile  │\n                    │   (your data)       │\n                    └─────────────────────┘\n```\n\n---\n\n## Features\n\n- **🏠 Local-First**: Your data stays on your machine by default\n- **📋 Structured Profiles**: Identity, tech stack, knowledge, skills\n- **🔌 MCP Standard**: Works with any MCP-compliant agent\n- **✏️ Human-in-the-Loop**: Agents can *propose* updates, you *approve* them\n- **🔧 Extensible Schema**: Add custom fields without modifying code\n- **🔒 Skills Privacy**: Control which skills are visible to agents (public/private/team)\n- **🤖 Agent-Callable Skills**: Define skills that AI agents can invoke on your behalf\n- **📄 Resume Import**: Bootstrap your profile from existing resume/CV\n- **📚 Knowledge Sources**: Books, docs, courses, articles - unified learning model\n- **👥 Team Sync**: Share coding standards across your team\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install from PyPI\npip install tilde-ai\n\n# Initialize your profile\ntilde init\n```\n\n<details>\n<summary>Development Installation</summary>\n\n```bash\n# Clone the repository\ngit clone https://github.com/topskychen/tilde.git\ncd tilde\n\n# Install with uv\nuv sync\n\n# Run locally\nuv run tilde init\n```\n</details>\n\n### Configure Cursor\n\nAdd to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global access):\n\n```json\n{\n  \"mcpServers\": {\n    \"tilde\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tilde-ai\"]\n    }\n  }\n}\n```\n\nOnce configured, you'll see tilde in your MCP servers with all available tools and resources:\n\n![Cursor MCP Settings](docs/images/cursor-mcp-settings.png)\n\n### Configure Antigravity\n\nAdd to `.gemini/antigravity/settings.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"tilde\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tilde-ai\"]\n    }\n  }\n}\n```\n\n### Configure Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"tilde\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tilde-ai\"]\n    }\n  }\n}\n```\n\n### Example Usage\n\nOnce configured, your AI agent can access your profile. Try asking:\n\n> **\"What is my name?\"**\n\nThe agent will use the `get_profile` tool to fetch your identity and respond with your name and role:\n\n![Cursor Demo](docs/images/cursor-demo.png)\n\n### Create Your Profile\n\nEdit `~/.tilde/profile.yaml`:\n\n```yaml\nschema_version: \"1.0.0\"\n\nuser_profile:\n  identity:\n    name: \"John Doe\"\n    role: \"Full Stack Developer\"\n    years_experience: 10\n    # Add any custom fields you need:\n    timezone: \"America/Los_Angeles\"\n    pronouns: \"they/them\"\n\n  tech_stack:\n    languages:\n      - TypeScript\n      - Python\n      - Go\n    frameworks:\n      - React\n      - FastAPI\n      - Next.js\n    preferences:\n      - \"Prefer composition over inheritance\"\n      - \"Write tests before implementation (TDD)\"\n      - \"Use descriptive variable names over comments\"\n    environment: \"VS Code, Docker, Linux/MacOS\"\n\n  # Knowledge sources: books, docs, courses, articles, etc.\n  knowledge:\n    domains:\n      web_development: \"Focus on performance and accessibility\"\n      ml_ops: \"Experience deploying ML models to production\"\n    \n    sources:\n      - title: \"Clean Code\"\n        source_type: \"book\"\n        insights:\n          - \"Functions should do one thing\"\n          - \"Prefer meaningful names over documentation\"\n      - title: \"React Documentation\"\n        source_type: \"document\"\n        url: \"https://react.dev\"\n        insights:\n          - \"Prefer Server Components for data fetching\"\n\n  # Agent-callable skills (Anthropic SKILL.md format)\n  skills:\n    - name: \"code-formatter\"\n      description: \"Format code using project conventions\"\n      visibility: \"public\"\n      tags: [\"automation\", \"code-quality\"]\n    - name: \"deploy-staging\"\n      description: \"Deploy current branch to staging environment\"\n      visibility: \"team\"\n    - name: \"expense-reporter\"\n      description: \"Generate expense reports from receipts\"\n      visibility: \"private\"\n\nteam_context:\n  organization: \"Acme Corp\"\n  coding_standards: \"ESLint + Prettier, PR reviews required\"\n  architecture_patterns: \"Monorepo with shared packages\"\n  do_not_use:\n    - \"jQuery\"\n    - \"Class components in React\"\n```\n\n---\n\n## MCP Resources\n\ntilde exposes these resources to agents:\n\n| Resource URI | Description |\n|-------------|-------------|\n| `tilde://user/profile` | Full user profile |\n| `tilde://user/identity` | Name, role, experience, custom fields |\n| `tilde://user/tech_stack` | Languages, preferences, environment |\n| `tilde://user/knowledge` | Knowledge sources, domains, projects |\n| `tilde://user/skills` | Skills (filtered by visibility) |\n| `tilde://user/experience` | Work history |\n| `tilde://user/education` | Education background |\n| `tilde://user/projects` | Personal/open-source projects |\n| `tilde://user/publications` | Papers and publications |\n| `tilde://team/context` | Team coding standards and patterns |\n\n---\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_profile` | Retrieve full or partial profile |\n| `get_team_context` | Get team-specific context |\n| `propose_update` | Agent proposes a profile update (queued for approval) |\n| `list_pending_updates` | List updates awaiting user approval |\n\n---\n\n## CLI Commands\n\n```bash\ntilde init                    # Create default profile\ntilde show                    # Display current profile\ntilde show skills             # Show skills section only\ntilde show --full             # Show full content without truncation\ntilde edit                    # Open profile in $EDITOR\ntilde config                  # Show current configuration\ntilde pending                 # List pending agent updates\ntilde approve <id> [id2...]   # Approve one or more updates\ntilde reject <id> [id2...]    # Reject one or more updates\ntilde approve --all           # Approve all pending updates\ntilde reject --all            # Reject all pending updates\ntilde approve --all -e <id>   # Approve all except one\ntilde log                     # View update history\ntilde ingest <file>           # Extract insights from a document\ntilde export --format json    # Export profile\n```\n\n### Document Ingestion\n\n```bash\n# Ingest a book and extract insights\ntilde ingest \"~/Books/DDIA.pdf\" --topic data_systems\n\n# Dry run to preview what would be extracted\ntilde ingest notes.md --dry-run\n\n# Auto-approve high-confidence updates\ntilde ingest paper.pdf --auto-approve 0.8\n```\n\n### Resume Import\n\nBootstrap your profile from an existing resume:\n\n```bash\n# Import resume (PDF, DOCX, or text)\ntilde ingest ~/Documents/resume.pdf --type resume\n\n# Preview what would be extracted\ntilde ingest resume.pdf --type resume --dry-run\n\n# Auto-approve high-confidence items\ntilde ingest resume.pdf --type resume --auto-approve 0.8\n```\n\nThe resume importer extracts:\n- **Identity**: Name, role, years of experience\n- **Experience**: Work history with companies, roles, dates\n- **Education**: Degrees, institutions, graduation years\n- **Tech Stack**: Programming languages, frameworks, tools\n- **Projects**: Personal and open-source projects\n- **Publications**: Papers, patents, articles\n\n### Skills Management\n\nManage Anthropic-format skills with full bundling support:\n\n```bash\n# Import skills from Anthropic skills directory\ntilde skills import /path/to/skills\n\n# Import specific skills by name\ntilde skills import /path/to/skills -n mcp-builder -n pdf\n\n# Dry run to preview import\ntilde skills import ./skills --dry-run\n\n# Import as private skills\ntilde skills import ./skills --visibility private\n\n# List all imported skills\ntilde skills list\n\n# Export skills to Anthropic format\ntilde skills export ./my-skills\n\n# Export specific skill\ntilde skills export ./output -n mcp-builder\n\n# Delete skills\ntilde skills delete skill-name\ntilde skills delete --all --force\n```\n\nThe skill importer bundles:\n- **SKILL.md**: Skill content with YAML frontmatter\n- **scripts/**: Python scripts and utilities\n- **references/**: Documentation files\n- **templates/**: Template files\n- **assets/**: Static assets\n- **Root files**: LICENSE.txt, etc.\n\nAll bundled resources are preserved through import → persist → export.\n\n### Team Management\n\n```bash\n# Create a team\ntilde team create myteam --name \"My Startup\" --org \"ACME Corp\"\n\n# Activate team context (applies to all profile queries)\ntilde team activate myteam\n\n# Sync team config from URL or git repo\ntilde team sync https://example.com/team.json --activate\ntilde team sync git@github.com:myorg/team-config.git --activate\n\n# List and manage teams\ntilde team list\ntilde team show\ntilde team edit\ntilde team deactivate\n```\n\n---\n\n## Storage Backends\n\ntilde supports multiple storage backends:\n\n| Backend | Use Case | Command |\n|---------|----------|---------|\n| **YAML** (default) | Human-readable, git-friendly | `TILDE_STORAGE=yaml` |\n| **SQLite** | Queryable, memories, faster at scale | `TILDE_STORAGE=sqlite` |\n| **Mem0** | Semantic search via embeddings | `TILDE_STORAGE=mem0` |\n\n```bash\n# Use SQLite backend\nexport TILDE_STORAGE=sqlite\ntilde init\n\n# Query profile fields (SQLite only)\nuv run python -c \"\nfrom tilde.storage import get_storage\nstorage = get_storage(backend='sqlite')\nprint(storage.query('%languages%'))\n\"\n```\n\n---\n\n## Configuration\n\ntilde uses a centralized configuration for LLM and embedding settings. Configuration is stored in `~/.tilde/config.yaml` and can be synced across devices.\n\n### Configuration Priority\n\n1. **Environment variables** (highest priority)\n2. **Config file** (`~/.tilde/config.yaml`)\n3. **Built-in defaults** (lowest priority)\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `GOOGLE_API_KEY` | Google/Gemini API key (primary) | Required |\n| `OPENAI_API_KEY` | OpenAI API key (fallback) | Optional |\n| `TILDE_LLM_MODEL` | LLM model for document ingestion | `gemini-3-flash-preview` |\n| `TILDE_EMBEDDING_MODEL` | Embedding model for semantic search | `gemini-embedding-001` |\n| `TILDE_STORAGE` | Storage backend (yaml, sqlite, mem0) | `yaml` |\n| `TILDE_PROFILE` | Custom profile path | `~/.tilde/profile.yaml` |\n\n### Managing Configuration\n\n```bash\n# View current configuration\ntilde config\n\n# Save settings to config file (for syncing across devices)\ntilde config --save\n\n# Modify a setting and save\ntilde config --set llm_model=gemini-1.5-pro\n\n# Show config file path\ntilde config --path\n```\n\n> **Note**: API keys are NEVER saved to the config file for security. Always set them via environment variables.\n\n### Quick Setup\n\n```bash\n# Minimal setup (just one API key!)\nexport GOOGLE_API_KEY=\"your-google-api-key\"\n\n# Save your settings for this device\ntilde config --save\n\n# Now you can use all features\ntilde ingest paper.pdf\n```\n\n### Syncing Across Devices\n\nThe config file at `~/.tilde/config.yaml` is designed to be synced:\n\n1. **Via dotfiles repo**: Add `~/.tilde/` to your dotfiles\n2. **Via cloud sync**: Dropbox, iCloud, or similar\n3. **Manually**: Copy the file to new devices\n\nExample config file:\n```yaml\nllm_model: gemini-3-flash-preview\nllm_temperature: 0.7\nembedding_model: gemini-embedding-001\nembedding_dimensions: 768\nstorage_backend: yaml\n```\n\n### Programmatic Configuration\n\n```python\nfrom tilde.config import get_config, call_llm, get_embedding, save_config\n\n# Check current config\nconfig = get_config()\nprint(f\"Provider: {config.provider}\")\nprint(f\"LLM Model: {config.llm_model}\")\n\n# Use directly\nresponse = call_llm(\"Summarize this document...\")\nembedding = get_embedding(\"Some text to embed\")\n```\n\n---\n\n## Roadmap\n\n- [x] **Phase 1**: MVP with profile reading\n- [x] **Phase 2**: Agent-proposed updates with approval flow\n- [x] **Phase 3**: Document ingestion (books, PDFs)\n- [x] **Phase 4**: Team sync for B2B use cases\n- [x] **Phase 5**: SQLite and Mem0 storage backends\n- [x] **Phase 6**: Skill Management (Anthropic SKILL.md format)\n  - [x] Batch import from directory with `tilde skills import`\n  - [x] Export to directory with `tilde skills export`\n  - [x] Full bundling of scripts, references, templates, assets\n  - [x] Deduplication by skill name\n\n---\n\n## Why \"tilde\"?\n\nIn Unix, `~` (tilde) represents your home directory — the place where your personal configuration lives. **tilde** is the home for your AI identity.\n\n---\n\n## Philosophy\n\n1. **Your Data, Your Control**: Local by default, sync only if you choose\n2. **Human-in-the-Loop**: Agents propose, humans decide\n3. **Portable & Open**: Export anytime, no lock-in, works with any MCP tool\n4. **Progressive Disclosure**: Start simple, add complexity as needed\n\n---\n\n## License\n\nMIT\n\n---\n\n<p align=\"center\">\n  <i>Configure once. Use everywhere. Your data, your control.</i>\n</p>\n",
  "bytes": 13998,
  "sha": "6fed529c18c7d51e8677f97b081c6c21e54e702b232534033a759f24c4283743",
  "repo_slug": "topskychen/tilde",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_topskychen_tilde_add32953/readme"
}