hermify-mcp 0.1.0__tar.gz

hermify_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,106 @@
+name: 🚀 Build, Test, and Release
+
+on:
+  # Trigger on semantic version tags (e.g., v0.2.0)
+  push:
+    tags:
+      - 'v*'
+  # Allow manual triggering from the GitHub Actions UI
+  workflow_dispatch:
+
+jobs:
+  # -------------------------------------------------------------------
+  # Job 1: Build & Verify
+  # -------------------------------------------------------------------
+  build-and-test:
+    name: 🧪 Build & Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: 🧹 Lint (Ruff)
+        run: uv run ruff check .
+
+      - name: 🧠 Type Check (Mypy)
+        run: uv run mypy .
+
+      - name: 🧪 Run Tests (Pytest)
+        run: uv run pytest -v
+
+      - name: 📦 Build Package
+        run: uv build
+
+      - name: Upload Build Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-dist
+          path: dist/
+          retention-days: 7
+
+  # -------------------------------------------------------------------
+  # Job 2: Publish to PyPI (Trusted Publishing / OIDC)
+  # -------------------------------------------------------------------
+  publish-to-pypi:
+    name: 📤 Publish to PyPI
+    needs: build-and-test
+    runs-on: ubuntu-latest
+    # The environment name MUST match the one configured in PyPI settings
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hermify-mcp
+    permissions:
+      # CRITICAL: This permission is required for OIDC Trusted Publishing
+      id-token: write  
+    steps:
+      - name: Download Build Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # NOTE: We intentionally DO NOT provide user/password. 
+        # The action uses the id-token to authenticate via OIDC.
+
+  # -------------------------------------------------------------------
+  # Job 3: Create GitHub Release
+  # -------------------------------------------------------------------
+  github-release:
+    name: 🏷️ Create GitHub Release
+    needs: publish-to-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # Required to create releases
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all history for release notes
+
+      - name: Download Build Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          draft: false
+          prerelease: false

hermify_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

hermify_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

hermify_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+
+# Contributing to hermify-mcp
+
+Welcome! We're building the future of cross-agent memory and skill sharing. This guide will help you get set up and understand our architectural principles.
+
+## 🛠️ Development Setup
+
+We use [`uv`](https://github.com/astral-sh/uv) for lightning-fast dependency management and Python versioning.
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/your-org/hermify-mcp.git
+   cd hermify-mcp
+   ```
+
+2. **Install dependencies and set up the environment:**
+   ```bash
+   uv sync
+   ```
+
+3. **Run the test suite to verify your setup:**
+   ```bash
+   uv run pytest
+   ```
+
+## 🏗️ Architectural Principles
+
+Before writing code, please internalize these core design pillars:
+
+1. **Local-First, Dataset-Backed**: All MCP tool writes MUST go to the local DuckDB buffer first. Network calls to Hugging Face Hub are strictly asynchronous (handled by `sync_push`). The agent loop must never block on I/O.
+2. **Event-Sourced Immutability**: Skills and memory are not "updated" in place. State changes (e.g., `draft` → `active`) are handled by appending new rows with incremented versions or status flags. 
+3. **Extensible Storage**: The `DatasetStore` should implement a clear interface. If you are adding a new storage backend, ensure it adheres to the same ACID and audit-chain guarantees as the DuckDB implementation.
+
+## 🧪 Test-Driven Development (TDD) Workflow
+
+We strictly follow TDD. **Do not submit a PR without tests.**
+
+1. **Write the test first**: Define the expected behavior in `tests/`. Mock external dependencies (like the HF Hub API or LLM Judge).
+   ```python
+   def test_propose_skill_creates_draft(store):
+       skill_md = "name: test\n---\nBody"
+       result = store.propose_skill(skill_md, agent_id="agent-1")
+       assert result['status'] == 'draft'
+   ```
+2. **Watch it fail**: Run `uv run pytest tests/test_dataset_store.py::test_propose_skill_creates_draft`.
+3. **Write the minimal code**: Implement the feature in `src/hermify_mcp/` to make the test pass.
+4. **Refactor**: Clean up the code while keeping the test green.
+
+## 📝 Code Quality & Linting
+
+We enforce strict code quality standards. Before pushing, run:
+
+```bash
+# Format and lint
+uv run ruff format .
+uv run ruff check . --fix
+
+# Type checking
+uv run mypy src/hermify_mcp
+```
+
+## 🚀 Pull Request Process
+
+1. Create a feature branch: `git checkout -b feat/your-feature-name`
+2. Ensure all tests pass: `uv run pytest`
+3. Ensure linting and typing pass.
+4. Open a Pull Request with a clear description of the problem solved and how the TDD approach was applied.
+5. A maintainer will review, focusing on architectural alignment and test coverage.
+
+## 💡 Questions?
+
+Open an issue or start a discussion in the GitHub repo. We're happy to help you navigate the codebase!

hermify_mcp-0.1.0/Dockerfile

@@ -0,0 +1,26 @@
+# Dockerfile
+FROM python:3.11-slim
+
+# Install uv for lightning-fast dependency resolution
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PORT=7860 \
+    HERMIFY_HOME=/data/.hermify
+
+# Set working directory
+WORKDIR /app
+
+# Copy project files
+COPY . .
+
+# Install dependencies and the package itself
+RUN uv sync --frozen
+
+# Expose the port HF Spaces expects
+EXPOSE 7860
+
+# Run the CLI directly in HTTP mode
+# We use /data/.hermify so we can mount a persistent volume later if needed
+CMD ["uv", "run", "hermify", "serve", "--transport", "http", "--host", "0.0.0.0", "--port", "7860"]

hermify_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 hermify-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermify_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: hermify-mcp
+Version: 0.1.0
+Summary: Add your description here
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: datasets>=5.0.0
+Requires-Dist: duckdb>=1.5.3
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.26.7
+Description-Content-Type: text/markdown
+
+# hermify-mcp
+
+> Cross-agent, dataset-backed skill and memory sync via MCP.
+> Hermify your agent interactions - push from Claude, pull into Gemini, improve without friction.
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![agentskills.io](https://img.shields.io/badge/skills-agentskills.io-purple)](https://agentskills.io)
+
+---
+
+## What it does
+
+`hermify-mcp` is an MCP server that gives any agent runtime a shared, **event-sourced, dataset-backed** knowledge base following the [agentskills.io](https://agentskills.io) open standard. 
+
+Instead of relying on traditional file-based version control, `hermify-mcp` treats agent skills, memory, and logs as structured, queryable data. It uses a **local-first DuckDB buffer** for lightning-fast, non-blocking agent interactions, which seamlessly syncs to **Hugging Face Datasets** as the immutable source of truth.
+
+```text
+Claude session ──► hermify_log() ──► Local DuckDB Buffer (Instant, ACID)
+                                              │
+                                        (Async Sync)
+                                              │
+                               Hugging Face Datasets (Parquet Shards)
+                                              │
+                              Gemini / Hermes / next Claude
+                              session pulls & queries on start
+```
+
+**Non-intrusive by design.** The server never injects into the agent loop. Agents call `propose_skill` or `hermify_log` post-session. The main workflow is never blocked waiting for network sync.
+
+---
+
+## 🚀 Quick Start & Agent Setup
+
+The recommended way to run `hermify-mcp` is via **`uvx`**, which allows your agent runtime to spawn the server in an isolated, ephemeral environment without polluting your global Python packages.
+
+### 1. Bootstrap your local configuration (One-time setup)
+Run this in your terminal to create your local DuckDB buffer and configure your Hugging Face target.
+
+```bash
+# Install uv if you haven't already (https://docs.astral.sh/uv/)
+# Bootstrap local config (creates ~/.hermify/config.yaml)
+uvx hermify-mcp init --hf-repo your-username/hermify-agent-memory --mode hf_push
+
+# Optional: Enable YOLO auto-approval mode (uses LLM-as-a-Judge)
+# uvx hermify-mcp init --hf-repo your-username/hermify-agent-memory --mode hf_push --yolo
+```
+
+### 2. Connect your Agent Runtime
+
+#### Option A: Local Private Brain (Claude Desktop / Cursor / Windsurf)
+Add the following to your MCP client configuration. This uses `uvx` to run the server locally via `stdio`. 
+
+*Note: We inject `HF_TOKEN` via the `env` block so the server can sync to Hugging Face.*
+
+**Claude Desktop (`claude_desktop_config.json`)** / **Cursor (`mcp.json`)**:
+```json
+{
+  "mcpServers": {
+    "hermify": {
+      "command": "uvx",
+      "args": ["hermify-mcp", "serve", "--transport", "stdio"],
+      "env": {
+        "HF_TOKEN": "hf_YOUR_HUGGINGFACE_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+#### Option B: Shared Team Brain (Hugging Face Spaces / Remote HTTP)
+Want to host a centralized, team-wide agent brain or a public demo? You can deploy `hermify-mcp` to Hugging Face Spaces using Docker. 
+
+This allows multiple agents (or multiple users) to connect to the same shared memory and skill library via HTTP, without needing to manage local files or sync conflicts.
+
+👉 **[Read the full Docker Deployment Guide here](docs/DEPLOY_HF_SPACES.md)**
+
+Once your Space is deployed and running, you don't use `uvx` or `stdio`. Instead, point your agent's MCP configuration directly to your Space's URL.
+
+Update your agent's MCP configuration (e.g., `claude_desktop_config.json` or Cursor's `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "hermify-team-brain": {
+      "url": "https://YOUR_USERNAME-hermify-team-brain.hf.space/mcp"
+    }
+  }
+}
+```
+*Note: FastMCP's HTTP transport automatically handles the `/mcp` or `/sse` routing based on the client's negotiation.*
+
+---
+
+## 🏗️ Architecture
+
+`hermify-mcp` is built on a pluggable storage architecture, making it easy to scale or swap backends while maintaining a consistent MCP tool surface.
+
+```text
+src/hermify_mcp/
+├── config.py           # HermifyConfig (Pydantic) + domain models
+├── dataset_store.py    # Local-first DuckDB store (Skills, Memory, Audit Chain)
+├── hf_sync.py          # Hugging Face Datasets sync engine (Parquet <-> Hub)
+├── eval.py             # LLM-as-a-Judge evaluation pipeline (YOLO governance)
+├── server.py           # FastMCP server - dataset-native tools
+└── cli.py              # Typer CLI (hermify init/serve/sync)
+```
+
+### Governance & Approval Modes
+Every skill write goes through a strict state machine (`draft` → `sandbox` → `active`).
+
+| Mode | Behaviour |
+|---|---|
+| `human_review` | Skills stay `draft`. Humans review via HF Hub UI or CLI before promoting to `active`. |
+| `yolo_eval` | An LLM-as-a-Judge automatically evaluates drafts. High-scoring skills auto-promote to `sandbox` (probationary use) or `active` (pure YOLO). |
+| `local_only` | Skills and memory stay in the local DuckDB buffer. No network calls. Default for air-gapped environments. |
+
+---
+
+## 🛠️ CLI Reference
+
+While agents interact with the server via MCP, you can manage your local brain directly from the terminal.
+
+```bash
+# Show help
+uvx hermify-mcp --help
+
+# Initialize / Reconfigure
+uvx hermify-mcp init --home ~/.hermify --hf-repo user/repo --mode hf_push --yolo
+
+# Manual Sync Operations (Useful for cron jobs or CI/CD)
+uvx hermify-mcp sync push      # Force push local DuckDB to HF Hub
+uvx hermify-mcp sync pull      # Pull latest Parquet shards from HF Hub
+uvx hermify-mcp sync status    # View local buffer metrics and sync state
+
+# Start server manually (defaults to stdio)
+uvx hermify-mcp serve
+uvx hermify-mcp serve --transport http --port 8742
+```
+
+---
+
+## 🧰 MCP Tools Surface
+
+### Skills & Governance
+| Tool | Description |
+|---|---|
+| `propose_skill` | Append a new skill draft to the local dataset. Triggers YOLO eval if enabled. |
+| `evaluate_skill` | Manually trigger the LLM Judge to score a draft and auto-transition state. |
+| `approve_skill` | Human override to promote a `draft` or `sandbox` skill to `active`. |
+| `search_skills` | Semantic or keyword search across the active dataset. |
+
+### Core: hermify_log
+```python
+hermify_log(
+  raw_transcript,   # full session text
+  skill_md,         # pre-generated SKILL.md from reflective phase
+  source_agent,     # "claude" | "gemini" | "hermes"
+  session_id,
+  task_goal,
+)
+```
+Stores the log + creates a draft skill in the local buffer. One call = full hermification.
+
+### Sync & Memory
+| Tool | Description |
+|---|---|
+| `append_memory` | Append semantic memory to the local dataset buffer. |
+| `get_memory` | Retrieve chronological memory entries for an agent. |
+| `sync_status` | Show local buffer size, last sync timestamp, and HF Hub revision. |
+| `sync_push` | Batch local DuckDB changes into Parquet and push to HF Hub. |
+| `sync_pull` | Download latest Parquet shards from HF Hub and merge into local DB. |
+
+---
+
+## 🧩 Extensibility
+
+The storage layer is abstracted. While DuckDB + Hugging Face Datasets is the default, the `BaseStore` protocol allows you to implement custom backends (e.g., PostgreSQL, LanceDB, or cloud object storage) without changing the MCP server interface.
+
+Similarly, the `EvalJudge` protocol allows you to plug in any LLM (OpenAI, Anthropic, Ollama) for YOLO governance.
+
+---
+
+## 🤝 Contributing
+
+We follow strict TDD. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting PRs.
+
+```bash
+# Clone and setup
+git clone https://github.com/your-org/hermify-mcp.git
+cd hermify-mcp
+uv sync
+
+# Run tests
+uv run pytest
+
+# Type checking
+uv run mypy .
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE)

hermify_mcp-0.1.0/README.md

@@ -0,0 +1,204 @@
+# hermify-mcp
+
+> Cross-agent, dataset-backed skill and memory sync via MCP.
+> Hermify your agent interactions - push from Claude, pull into Gemini, improve without friction.
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![agentskills.io](https://img.shields.io/badge/skills-agentskills.io-purple)](https://agentskills.io)
+
+---
+
+## What it does
+
+`hermify-mcp` is an MCP server that gives any agent runtime a shared, **event-sourced, dataset-backed** knowledge base following the [agentskills.io](https://agentskills.io) open standard. 
+
+Instead of relying on traditional file-based version control, `hermify-mcp` treats agent skills, memory, and logs as structured, queryable data. It uses a **local-first DuckDB buffer** for lightning-fast, non-blocking agent interactions, which seamlessly syncs to **Hugging Face Datasets** as the immutable source of truth.
+
+```text
+Claude session ──► hermify_log() ──► Local DuckDB Buffer (Instant, ACID)
+                                              │
+                                        (Async Sync)
+                                              │
+                               Hugging Face Datasets (Parquet Shards)
+                                              │
+                              Gemini / Hermes / next Claude
+                              session pulls & queries on start
+```
+
+**Non-intrusive by design.** The server never injects into the agent loop. Agents call `propose_skill` or `hermify_log` post-session. The main workflow is never blocked waiting for network sync.
+
+---
+
+## 🚀 Quick Start & Agent Setup
+
+The recommended way to run `hermify-mcp` is via **`uvx`**, which allows your agent runtime to spawn the server in an isolated, ephemeral environment without polluting your global Python packages.
+
+### 1. Bootstrap your local configuration (One-time setup)
+Run this in your terminal to create your local DuckDB buffer and configure your Hugging Face target.
+
+```bash
+# Install uv if you haven't already (https://docs.astral.sh/uv/)
+# Bootstrap local config (creates ~/.hermify/config.yaml)
+uvx hermify-mcp init --hf-repo your-username/hermify-agent-memory --mode hf_push
+
+# Optional: Enable YOLO auto-approval mode (uses LLM-as-a-Judge)
+# uvx hermify-mcp init --hf-repo your-username/hermify-agent-memory --mode hf_push --yolo
+```
+
+### 2. Connect your Agent Runtime
+
+#### Option A: Local Private Brain (Claude Desktop / Cursor / Windsurf)
+Add the following to your MCP client configuration. This uses `uvx` to run the server locally via `stdio`. 
+
+*Note: We inject `HF_TOKEN` via the `env` block so the server can sync to Hugging Face.*
+
+**Claude Desktop (`claude_desktop_config.json`)** / **Cursor (`mcp.json`)**:
+```json
+{
+  "mcpServers": {
+    "hermify": {
+      "command": "uvx",
+      "args": ["hermify-mcp", "serve", "--transport", "stdio"],
+      "env": {
+        "HF_TOKEN": "hf_YOUR_HUGGINGFACE_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+#### Option B: Shared Team Brain (Hugging Face Spaces / Remote HTTP)
+Want to host a centralized, team-wide agent brain or a public demo? You can deploy `hermify-mcp` to Hugging Face Spaces using Docker. 
+
+This allows multiple agents (or multiple users) to connect to the same shared memory and skill library via HTTP, without needing to manage local files or sync conflicts.
+
+👉 **[Read the full Docker Deployment Guide here](docs/DEPLOY_HF_SPACES.md)**
+
+Once your Space is deployed and running, you don't use `uvx` or `stdio`. Instead, point your agent's MCP configuration directly to your Space's URL.
+
+Update your agent's MCP configuration (e.g., `claude_desktop_config.json` or Cursor's `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "hermify-team-brain": {
+      "url": "https://YOUR_USERNAME-hermify-team-brain.hf.space/mcp"
+    }
+  }
+}
+```
+*Note: FastMCP's HTTP transport automatically handles the `/mcp` or `/sse` routing based on the client's negotiation.*
+
+---
+
+## 🏗️ Architecture
+
+`hermify-mcp` is built on a pluggable storage architecture, making it easy to scale or swap backends while maintaining a consistent MCP tool surface.
+
+```text
+src/hermify_mcp/
+├── config.py           # HermifyConfig (Pydantic) + domain models
+├── dataset_store.py    # Local-first DuckDB store (Skills, Memory, Audit Chain)
+├── hf_sync.py          # Hugging Face Datasets sync engine (Parquet <-> Hub)
+├── eval.py             # LLM-as-a-Judge evaluation pipeline (YOLO governance)
+├── server.py           # FastMCP server - dataset-native tools
+└── cli.py              # Typer CLI (hermify init/serve/sync)
+```
+
+### Governance & Approval Modes
+Every skill write goes through a strict state machine (`draft` → `sandbox` → `active`).
+
+| Mode | Behaviour |
+|---|---|
+| `human_review` | Skills stay `draft`. Humans review via HF Hub UI or CLI before promoting to `active`. |
+| `yolo_eval` | An LLM-as-a-Judge automatically evaluates drafts. High-scoring skills auto-promote to `sandbox` (probationary use) or `active` (pure YOLO). |
+| `local_only` | Skills and memory stay in the local DuckDB buffer. No network calls. Default for air-gapped environments. |
+
+---
+
+## 🛠️ CLI Reference
+
+While agents interact with the server via MCP, you can manage your local brain directly from the terminal.
+
+```bash
+# Show help
+uvx hermify-mcp --help
+
+# Initialize / Reconfigure
+uvx hermify-mcp init --home ~/.hermify --hf-repo user/repo --mode hf_push --yolo
+
+# Manual Sync Operations (Useful for cron jobs or CI/CD)
+uvx hermify-mcp sync push      # Force push local DuckDB to HF Hub
+uvx hermify-mcp sync pull      # Pull latest Parquet shards from HF Hub
+uvx hermify-mcp sync status    # View local buffer metrics and sync state
+
+# Start server manually (defaults to stdio)
+uvx hermify-mcp serve
+uvx hermify-mcp serve --transport http --port 8742
+```
+
+---
+
+## 🧰 MCP Tools Surface
+
+### Skills & Governance
+| Tool | Description |
+|---|---|
+| `propose_skill` | Append a new skill draft to the local dataset. Triggers YOLO eval if enabled. |
+| `evaluate_skill` | Manually trigger the LLM Judge to score a draft and auto-transition state. |
+| `approve_skill` | Human override to promote a `draft` or `sandbox` skill to `active`. |
+| `search_skills` | Semantic or keyword search across the active dataset. |
+
+### Core: hermify_log
+```python
+hermify_log(
+  raw_transcript,   # full session text
+  skill_md,         # pre-generated SKILL.md from reflective phase
+  source_agent,     # "claude" | "gemini" | "hermes"
+  session_id,
+  task_goal,
+)
+```
+Stores the log + creates a draft skill in the local buffer. One call = full hermification.
+
+### Sync & Memory
+| Tool | Description |
+|---|---|
+| `append_memory` | Append semantic memory to the local dataset buffer. |
+| `get_memory` | Retrieve chronological memory entries for an agent. |
+| `sync_status` | Show local buffer size, last sync timestamp, and HF Hub revision. |
+| `sync_push` | Batch local DuckDB changes into Parquet and push to HF Hub. |
+| `sync_pull` | Download latest Parquet shards from HF Hub and merge into local DB. |
+
+---
+
+## 🧩 Extensibility
+
+The storage layer is abstracted. While DuckDB + Hugging Face Datasets is the default, the `BaseStore` protocol allows you to implement custom backends (e.g., PostgreSQL, LanceDB, or cloud object storage) without changing the MCP server interface.
+
+Similarly, the `EvalJudge` protocol allows you to plug in any LLM (OpenAI, Anthropic, Ollama) for YOLO governance.
+
+---
+
+## 🤝 Contributing
+
+We follow strict TDD. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting PRs.
+
+```bash
+# Clone and setup
+git clone https://github.com/your-org/hermify-mcp.git
+cd hermify-mcp
+uv sync
+
+# Run tests
+uv run pytest
+
+# Type checking
+uv run mypy .
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE)