oyhub 0.2.0__py3-none-any.whl

oyhub/__init__.py

@@ -0,0 +1,12 @@
+"""OyHub — a local, always-on agent harness for engineers.
+
+One central skill library with per-project activation, persistent memory
+(Obsidian vault + SQLite FTS5 recall), and a background curator loop —
+exposed to Claude Desktop / Claude Code / Cursor as an MCP server.
+
+Fixes two problems:
+  1. Skill sprawl  — skills scattered across projects, nothing organized.
+  2. Context exhaustion — knowledge lost when the context window fills up.
+"""
+
+__version__ = "0.2.0"

oyhub/__main__.py

@@ -0,0 +1,35 @@
+"""CLI: `python -m oyhub` runs the MCP server (stdio).
+`python -m oyhub doctor` prints a health check."""
+
+from __future__ import annotations
+
+import sys
+
+from .config import HubConfig
+from .server import Hub, serve
+
+
+def doctor() -> int:
+    cfg = HubConfig()
+    cfg.ensure_dirs()
+    hub = Hub(cfg)
+    print(f"oyhub home : {cfg.home}")
+    print(f"vault         : {cfg.vault_path}")
+    print(f"skills        : {len(hub.skills.all_names())}")
+    print(f"projects      : {', '.join(hub.skills.list_projects()) or '(none)'}")
+    print(f"sessions db   : {cfg.db_path} "
+          f"({'exists' if cfg.db_path.exists() else 'will be created'})")
+    print(f"curator due   : {hub.curator.due()}")
+    print("status        : ok")
+    return 0
+
+
+def main() -> int:
+    if len(sys.argv) > 1 and sys.argv[1] == "doctor":
+        return doctor()
+    serve()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

oyhub/config.py

@@ -0,0 +1,58 @@
+"""OyHub configuration. Everything lives under ~/.oyhub by default;
+the Obsidian vault is wherever the user's vault already is."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def _home() -> Path:
+    return Path(os.getenv("OYHUB_HOME", "~/.oyhub")).expanduser()
+
+
+@dataclass
+class HubConfig:
+    home: Path = field(default_factory=_home)
+    # Obsidian vault root (the folder Obsidian opens). Memory notes go into
+    # a "OyHub" subfolder there. If unset, falls back to ~/.oyhub/vault
+    # (still plain markdown — you can open it as a vault later).
+    vault_path: Path = field(
+        default_factory=lambda: Path(
+            os.getenv("OYHUB_VAULT", "")
+        ).expanduser()
+        if os.getenv("OYHUB_VAULT")
+        else _home() / "vault"
+    )
+    memory_folder: str = "OyHub"
+    # Curated-memory snapshot budget (chars, not tokens — model-independent).
+    snapshot_char_limit: int = 8000
+    # Curator policy.
+    curator_interval_hours: float = 6.0
+    skill_stale_days: int = 90
+
+    @property
+    def skills_dir(self) -> Path:
+        return self.home / "skills"
+
+    @property
+    def archive_dir(self) -> Path:
+        return self.home / "archive"
+
+    @property
+    def db_path(self) -> Path:
+        return self.home / "sessions.db"
+
+    @property
+    def projects_file(self) -> Path:
+        return self.home / "projects.json"
+
+    @property
+    def state_file(self) -> Path:
+        return self.home / "state.json"
+
+    def ensure_dirs(self) -> None:
+        for p in (self.home, self.skills_dir, self.archive_dir,
+                  self.vault_path / self.memory_folder):
+            p.mkdir(parents=True, exist_ok=True)

oyhub/curator.py

@@ -0,0 +1,144 @@
+"""The curator — loop engineering in the background.
+
+Runs periodically (and on server idle) to keep the hub healthy without any
+LLM calls in the MVP — pure policy, borrowed from Hermes' curator invariants:
+
+  * NEVER deletes — stale skills are archived (recoverable).
+  * Pinned skills bypass all automation.
+  * Dedupes curated-memory bullets (case-insensitive).
+  * Records every action it takes in a curator log note in the vault,
+    so the loop's work is visible to the user.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import time
+from dataclasses import dataclass, field
+
+from .config import HubConfig
+from .locks import read_json, update_json
+from .memory import VaultMemory
+from .skills import SkillStore
+
+
+@dataclass
+class CuratorReport:
+    archived_skills: list[str] = field(default_factory=list)
+    deduped_notes: dict = field(default_factory=dict)  # note name -> removed count
+    ran_at: str = ""
+
+    def summary(self) -> str:
+        bits = []
+        if self.archived_skills:
+            bits.append(f"archived {len(self.archived_skills)} stale skill(s): "
+                        + ", ".join(self.archived_skills))
+        removed = sum(self.deduped_notes.values())
+        if removed:
+            bits.append(f"removed {removed} duplicate memory entr(ies)")
+        return "; ".join(bits) or "nothing to do — hub is healthy"
+
+
+class Curator:
+    def __init__(self, cfg: HubConfig, skills: SkillStore, vault: VaultMemory):
+        self.cfg = cfg
+        self.skills = skills
+        self.vault = vault
+
+    # -- scheduling ------------------------------------------------------------
+
+    def due(self) -> bool:
+        state = self._read_state()
+        last = state.get("curator_last_run", 0.0)
+        return time.time() - last >= self.cfg.curator_interval_hours * 3600
+
+    def maybe_run(self) -> CuratorReport | None:
+        return self.run() if self.due() else None
+
+    # -- the loop body -----------------------------------------------------------
+
+    def run(self) -> CuratorReport:
+        report = CuratorReport(ran_at=_dt.datetime.now().isoformat(" ", "minutes"))
+        report.archived_skills = self._archive_stale_skills()
+        report.deduped_notes = self._dedupe_memory_notes()
+        self._write_state()
+        self._log_to_vault(report)
+        return report
+
+    def pin(self, skill_name: str) -> None:
+        def _pin(state: dict) -> dict:
+            state["pinned"] = sorted(set(state.get("pinned", [])) | {skill_name})
+            return state
+
+        update_json(self.cfg.state_file, {}, _pin)
+
+    def pinned(self) -> set[str]:
+        return set(self._read_state().get("pinned", []))
+
+    # -- policies ---------------------------------------------------------------
+
+    def _archive_stale_skills(self) -> list[str]:
+        cutoff = time.time() - self.cfg.skill_stale_days * 86400
+        usage = self.skills.usage()
+        pinned = self.pinned()
+        archived = []
+        for name in self.skills.all_names():
+            if name in pinned:
+                continue
+            rec = usage.get(name)
+            if rec is None:
+                continue  # never used since tracking began — grace period
+            if rec.get("last_used", time.time()) < cutoff:
+                if self.skills.remove(name):  # remove() archives, never deletes
+                    archived.append(name)
+        return archived
+
+    def _dedupe_memory_notes(self) -> dict:
+        out: dict[str, int] = {}
+        for path in sorted(self.vault.dir.glob("*.md")):
+            if path.name.startswith("Curator"):
+                continue
+            lines = path.read_text(encoding="utf-8").splitlines()
+            seen: set[str] = set()
+            kept: list[str] = []
+            removed = 0
+            for line in lines:
+                key = _normalize_bullet(line)
+                if key and key in seen:
+                    removed += 1
+                    continue
+                if key:
+                    seen.add(key)
+                kept.append(line)
+            if removed:
+                path.write_text("\n".join(kept) + "\n", encoding="utf-8")
+                out[path.name] = removed
+        return out
+
+    # -- bookkeeping --------------------------------------------------------------
+
+    def _read_state(self) -> dict:
+        return read_json(self.cfg.state_file, {})
+
+    def _write_state(self) -> None:
+        def _stamp(state: dict) -> dict:
+            state["curator_last_run"] = time.time()
+            return state
+
+        update_json(self.cfg.state_file, {}, _stamp)
+
+    def _log_to_vault(self, report: CuratorReport) -> None:
+        path = self.vault.dir / "Curator Log.md"
+        with path.open("a", encoding="utf-8") as f:
+            f.write(f"- {report.ran_at}: {report.summary()}\n")
+
+
+def _normalize_bullet(line: str) -> str:
+    """Key for dedupe: bullet text, lowercased, date-stamp stripped."""
+    s = line.strip()
+    if not s.startswith("- "):
+        return ""
+    s = s[2:]
+    if s.endswith(")*") and "*(" in s:
+        s = s[: s.rfind("*(")]
+    return " ".join(s.lower().split())

oyhub/guard.py

@@ -0,0 +1,52 @@
+"""Injection scanning for content that persists into future context windows.
+
+Memory entries and skills are re-injected into system prompts across every
+future session — a poisoned entry persists until explicitly removed. So
+anything flowing INTO those stores is scanned at write time (the Hermes
+``threat_patterns`` pattern: one source of truth, strictness proportional
+to persistence).
+
+Deliberately narrow: we block instruction-hijack phrasing and data-exfil
+link shapes, not legitimate engineering content. A skill body containing
+``curl`` or an API example must pass; "ignore all previous instructions"
+must not.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+# (compiled pattern, human-readable reason)
+_THREATS: list[tuple[re.Pattern, str]] = [
+    (re.compile(r"\bignore\s+(?:all\s+|any\s+)?(?:previous|prior|above|earlier)\s+"
+                r"(?:instructions?|context|prompts?)", re.I),
+     "instruction-override phrasing ('ignore previous instructions')"),
+    (re.compile(r"\bdisregard\s+(?:all\s+|your\s+)?(?:previous|prior|system)\s+"
+                r"(?:instructions?|prompts?)", re.I),
+     "instruction-override phrasing ('disregard prior instructions')"),
+    (re.compile(r"\bforget\s+(?:everything|all)\s+(?:you\s+know|above|previous)", re.I),
+     "instruction-override phrasing ('forget everything above')"),
+    (re.compile(r"\byou\s+are\s+now\s+(?:in\s+)?(?:developer|dan|jailbreak|god)\s*mode\b", re.I),
+     "jailbreak-mode phrasing"),
+    (re.compile(r"<\s*/?\s*system\s*>", re.I),
+     "embedded <system> tag"),
+    (re.compile(r"\bnew\s+system\s+prompt\s*:", re.I),
+     "system-prompt replacement phrasing"),
+    (re.compile(r"\bdo\s+not\s+(?:tell|inform|alert)\s+the\s+user\b", re.I),
+     "concealment instruction ('do not tell the user')"),
+    # Markdown link/image whose URL smuggles secrets in query params —
+    # the classic exfil channel for content rendered in a client.
+    (re.compile(r"\]\(\s*https?://[^)\s]*[?&][^)\s]*"
+                r"(?:token|secret|key|password|credential|auth)[^)\s]*=", re.I),
+     "markdown link with credential-shaped query parameter (possible exfil)"),
+]
+
+
+def first_threat(content: str) -> Optional[str]:
+    """Return a human-readable reason if *content* matches a threat pattern,
+    else None. Callers refuse the write and surface the reason."""
+    for pattern, reason in _THREATS:
+        if pattern.search(content):
+            return reason
+    return None

oyhub/locks.py

@@ -0,0 +1,70 @@
+"""Cross-process safety primitives.
+
+Multiple MCP clients (Claude Desktop, Claude Code, Cowork) each spawn their
+own OyHub process against the same on-disk state. Without locking, two
+processes doing read-modify-write on the same JSON file silently lose
+updates (last write wins). Every shared JSON file goes through
+:func:`update_json` — an exclusive-lock + atomic-replace critical section.
+
+POSIX uses ``fcntl.flock`` on a sidecar ``.lock`` file; on platforms without
+fcntl (Windows) we degrade to lock-free atomic replace, which still prevents
+torn files even if it can't prevent lost updates.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Callable, Iterator
+
+try:
+    import fcntl
+except ImportError:  # Windows
+    fcntl = None  # type: ignore[assignment]
+
+
+@contextmanager
+def locked(path: Path) -> Iterator[None]:
+    """Exclusive cross-process lock scoped to *path* (sidecar lockfile)."""
+    lock_path = path.parent / (path.name + ".lock")
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    handle = open(lock_path, "a+")
+    try:
+        if fcntl is not None:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        yield
+    finally:
+        try:
+            if fcntl is not None:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        finally:
+            handle.close()
+
+
+def read_json(path: Path, default: Any) -> Any:
+    if not path.exists():
+        return default
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return default
+
+
+def write_json_atomic(path: Path, data: Any) -> None:
+    """Write via temp file + os.replace — readers never see a torn file."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.parent / (path.name + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def update_json(path: Path, default: Any,
+                fn: Callable[[Any], Any]) -> Any:
+    """Atomic read-modify-write under an exclusive lock."""
+    with locked(path):
+        data = read_json(path, default)
+        data = fn(data)
+        write_json_atomic(path, data)
+        return data

oyhub/memory.py

@@ -0,0 +1,220 @@
+"""Memory layer — the fix for context exhaustion.
+
+Two stores, two jobs:
+
+  1. OBSIDIAN VAULT (curated memory) — bounded markdown notes per project plus
+     a global note. Human-readable, editable, graph-linked. Snapshot is read
+     at session start and injected once (frozen-snapshot pattern: mid-session
+     writes hit disk but never mutate an already-taken snapshot).
+
+  2. SQLITE + FTS5 (raw recall) — every exchange the client chooses to log is
+     full-text indexed. Recall is a *retrieval* call, not resident context:
+     instead of keeping 200k tokens alive, you search for the 5 messages that
+     matter. Zero LLM cost (BM25), returns actual stored text.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import sqlite3
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from .config import HubConfig
+from .guard import first_threat
+from .locks import locked
+
+_GLOBAL_NOTE = "Global.md"
+
+
+# ---------------------------------------------------------------------------
+# Curated memory — Obsidian vault
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class Snapshot:
+    global_notes: str
+    project_notes: str
+    project: str
+
+    def as_text(self) -> str:
+        parts = []
+        if self.global_notes.strip():
+            parts.append(f"## Global memory\n{self.global_notes.strip()}")
+        if self.project_notes.strip():
+            parts.append(f"## Project memory: {self.project}\n"
+                         f"{self.project_notes.strip()}")
+        return "\n\n".join(parts) or "(no curated memory yet)"
+
+
+class VaultMemory:
+    def __init__(self, cfg: HubConfig):
+        self.cfg = cfg
+        self.dir = cfg.vault_path / cfg.memory_folder
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def _note_path(self, project: Optional[str]) -> Path:
+        if project:
+            safe = "".join(c for c in project if c.isalnum() or c in "-_ ")
+            return self.dir / f"Project - {safe}.md"
+        return self.dir / _GLOBAL_NOTE
+
+    def add(self, entry: str, project: Optional[str] = None) -> str:
+        entry = " ".join(entry.split())
+        threat = first_threat(entry)
+        if threat:
+            raise ValueError(
+                f"memory blocked: {threat}. Memory persists into every future "
+                f"session's context, so this content cannot be stored."
+            )
+        path = self._note_path(project)
+        # Lock: two clients appending concurrently must not interleave writes
+        # or double-save past each other's dedupe check.
+        with locked(path):
+            existing = path.read_text(encoding="utf-8") if path.exists() else ""
+            if entry.lower() in existing.lower():
+                return "duplicate — already remembered"
+            stamp = _dt.date.today().isoformat()
+            with path.open("a", encoding="utf-8") as f:
+                if existing and not existing.endswith("\n"):
+                    f.write("\n")
+                f.write(f"- {entry} *({stamp})*\n")
+        return f"saved to {path.name}"
+
+    def snapshot(self, project: str = "") -> Snapshot:
+        budget = self.cfg.snapshot_char_limit
+        glob = self._read(self._note_path(None))
+        proj = self._read(self._note_path(project)) if project else ""
+        # Project memory gets priority; global fills the remainder, newest-first.
+        proj = _keep_newest(proj, budget)
+        glob = _keep_newest(glob, budget - len(proj))
+        return Snapshot(global_notes=glob, project_notes=proj, project=project)
+
+    def _read(self, path: Path) -> str:
+        return path.read_text(encoding="utf-8") if path.exists() else ""
+
+
+def _keep_newest(text: str, budget: int) -> str:
+    if budget <= 0:
+        return ""
+    if len(text) <= budget:
+        return text
+    kept, used = [], 0
+    for line in reversed([ln for ln in text.splitlines() if ln.strip()]):
+        if used + len(line) + 1 > budget:
+            break
+        kept.append(line)
+        used += len(line) + 1
+    return "\n".join(reversed(kept))
+
+
+# ---------------------------------------------------------------------------
+# Raw recall — SQLite + FTS5
+# ---------------------------------------------------------------------------
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS messages (
+    id INTEGER PRIMARY KEY,
+    session_id TEXT NOT NULL,
+    project TEXT NOT NULL DEFAULT '',
+    role TEXT NOT NULL,
+    content TEXT NOT NULL,
+    ts REAL NOT NULL
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
+    content, content='messages', content_rowid='id'
+);
+CREATE TRIGGER IF NOT EXISTS messages_ai AFTER INSERT ON messages BEGIN
+    INSERT INTO messages_fts(rowid, content) VALUES (new.id, new.content);
+END;
+"""
+
+
+class SessionStore:
+    def __init__(self, cfg: HubConfig):
+        cfg.ensure_dirs()
+        self.db_path = cfg.db_path
+
+    def _conn(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path, timeout=10.0)
+        # WAL: concurrent readers + one writer across processes (multiple MCP
+        # clients share this DB). busy_timeout makes writers queue instead of
+        # failing fast with "database is locked".
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA busy_timeout=10000")
+        conn.executescript(_SCHEMA)
+        return conn
+
+    def log(self, role: str, content: str, project: str = "",
+            session_id: str = "") -> str:
+        session_id = session_id or uuid.uuid4().hex[:12]
+        with self._conn() as conn:
+            conn.execute(
+                "INSERT INTO messages (session_id, project, role, content, ts)"
+                " VALUES (?,?,?,?,?)",
+                (session_id, project, role, content, time.time()),
+            )
+        return session_id
+
+    def search(self, query: str, project: str = "", limit: int = 5,
+               window: int = 2) -> list[dict]:
+        """FTS5 discovery: top hits (BM25), each with a ±window message
+        context from its session. Zero LLM cost."""
+        sql = (
+            "SELECT m.id, m.session_id, m.project, m.role, m.content, m.ts "
+            "FROM messages_fts f JOIN messages m ON m.id = f.rowid "
+            "WHERE messages_fts MATCH ? "
+        )
+        args: list = [_fts_escape(query)]
+        if project:
+            sql += "AND m.project = ? "
+            args.append(project)
+        sql += "ORDER BY rank LIMIT ?"
+        args.append(limit)
+
+        with self._conn() as conn:
+            hits = conn.execute(sql, args).fetchall()
+            out = []
+            seen_sessions: set[str] = set()
+            for mid, sid, proj, role, content, ts in hits:
+                if sid in seen_sessions:  # dedupe by session lineage
+                    continue
+                seen_sessions.add(sid)
+                ctx = conn.execute(
+                    "SELECT role, content FROM messages WHERE session_id=? "
+                    "AND id BETWEEN ? AND ? ORDER BY id",
+                    (sid, mid - window, mid + window),
+                ).fetchall()
+                out.append({
+                    "session_id": sid,
+                    "project": proj,
+                    "when": _dt.datetime.fromtimestamp(ts).isoformat(" ", "minutes"),
+                    "match": {"role": role, "content": content},
+                    "context": [{"role": r, "content": c} for r, c in ctx],
+                })
+        return out
+
+    def recent_sessions(self, limit: int = 10) -> list[dict]:
+        with self._conn() as conn:
+            rows = conn.execute(
+                "SELECT session_id, project, MIN(ts), COUNT(*), "
+                "substr(MIN(content), 1, 120) "
+                "FROM messages GROUP BY session_id "
+                "ORDER BY MIN(ts) DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+        return [
+            {"session_id": sid, "project": proj,
+             "started": _dt.datetime.fromtimestamp(ts).isoformat(" ", "minutes"),
+             "messages": n, "preview": prev}
+            for sid, proj, ts, n, prev in rows
+        ]
+
+
+def _fts_escape(query: str) -> str:
+    """Quote each term — protects against FTS5 syntax errors on user input."""
+    terms = [t.replace('"', '""') for t in query.split() if t]
+    return " ".join(f'"{t}"' for t in terms)

oyhub/server.py

@@ -0,0 +1,226 @@
+"""OyHub MCP server — stdio JSON-RPC, no dependencies.
+
+Implements the Model Context Protocol surface that Claude Desktop,
+Claude Code, and Cursor speak: initialize / tools/list / tools/call.
+Each tool call also gives the curator a chance to run (idle-triggered
+loop engineering — the Hermes pattern of maintenance without a daemon).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Callable
+
+from . import __version__
+from .config import HubConfig
+from .curator import Curator
+from .memory import SessionStore, VaultMemory
+from .skills import SkillStore
+
+PROTOCOL_VERSION = "2024-11-05"
+
+
+def _tool(name: str, description: str, properties: dict,
+          required: list[str] | None = None) -> dict:
+    return {
+        "name": name,
+        "description": description,
+        "inputSchema": {
+            "type": "object",
+            "properties": properties,
+            "required": required or [],
+        },
+    }
+
+
+class Hub:
+    """All tool handlers in one place — server transport stays dumb."""
+
+    def __init__(self, cfg: HubConfig | None = None):
+        self.cfg = cfg or HubConfig()
+        self.cfg.ensure_dirs()
+        self.skills = SkillStore(self.cfg)
+        self.vault = VaultMemory(self.cfg)
+        self.sessions = SessionStore(self.cfg)
+        self.curator = Curator(self.cfg, self.skills, self.vault)
+        self.active_project = ""
+
+    # ---- tool registry -------------------------------------------------------
+
+    def tool_schemas(self) -> list[dict]:
+        return [
+            _tool("project_activate",
+                  "Activate a project so skill listing and memory are scoped to it. "
+                  "Creates the project profile if new.",
+                  {"project": {"type": "string"},
+                   "tags": {"type": "array", "items": {"type": "string"},
+                            "description": "Skill tags relevant to this project."}},
+                  ["project"]),
+            _tool("skill_add",
+                  "Save a reusable skill to the central library. Description must "
+                  "be <=60 chars — it's the routing index.",
+                  {"name": {"type": "string"},
+                   "description": {"type": "string"},
+                   "body": {"type": "string"},
+                   "tags": {"type": "array", "items": {"type": "string"}}},
+                  ["name", "description", "body"]),
+            _tool("skill_list",
+                  "Compact index of skills (name + 60-char description), filtered "
+                  "to the active project's tags.",
+                  {"project": {"type": "string",
+                               "description": "Override the active project."}}),
+            _tool("skill_view",
+                  "Load one skill's full body (marks it as used).",
+                  {"name": {"type": "string"}}, ["name"]),
+            _tool("skill_search",
+                  "Keyword search across all skills regardless of project.",
+                  {"query": {"type": "string"}}, ["query"]),
+            _tool("memory_add",
+                  "Persist a curated memory entry (fact, preference, convention) "
+                  "to the Obsidian vault. Scoped to the active project unless "
+                  "global=true.",
+                  {"entry": {"type": "string"},
+                   "global": {"type": "boolean"}},
+                  ["entry"]),
+            _tool("memory_snapshot",
+                  "Read the frozen memory snapshot (global + active project). "
+                  "Call once at session start.",
+                  {}),
+            _tool("session_log",
+                  "Log an exchange into searchable history (SQLite FTS5). Call "
+                  "with the important content of a turn worth remembering.",
+                  {"role": {"type": "string", "enum": ["user", "assistant"]},
+                   "content": {"type": "string"},
+                   "session_id": {"type": "string"}},
+                  ["role", "content"]),
+            _tool("session_search",
+                  "Full-text search past conversations. Returns matches with "
+                  "surrounding context. Use instead of asking the user to repeat.",
+                  {"query": {"type": "string"},
+                   "limit": {"type": "integer"}},
+                  ["query"]),
+            _tool("session_recent",
+                  "Browse recent logged sessions chronologically.",
+                  {"limit": {"type": "integer"}}),
+            _tool("curator_run",
+                  "Run hub maintenance now: archive stale skills, dedupe memory.",
+                  {}),
+            _tool("curator_pin",
+                  "Pin a skill so the curator never auto-archives it.",
+                  {"name": {"type": "string"}}, ["name"]),
+        ]
+
+    def call(self, name: str, args: dict) -> Any:
+        handlers: dict[str, Callable[[dict], Any]] = {
+            "project_activate": self._project_activate,
+            "skill_add": lambda a: self.skills.add(
+                a["name"], a["description"], a["body"], a.get("tags")).name
+                + " saved",
+            "skill_list": lambda a: self.skills.index(
+                a.get("project") or self.active_project or None),
+            "skill_view": self._skill_view,
+            "skill_search": lambda a: self.skills.search(a["query"]),
+            "memory_add": lambda a: self.vault.add(
+                a["entry"],
+                project=None if a.get("global") else (self.active_project or None)),
+            "memory_snapshot": lambda a: self.vault.snapshot(
+                self.active_project).as_text(),
+            "session_log": lambda a: {"session_id": self.sessions.log(
+                a["role"], a["content"], project=self.active_project,
+                session_id=a.get("session_id", ""))},
+            "session_search": lambda a: self.sessions.search(
+                a["query"], limit=int(a.get("limit", 5))),
+            "session_recent": lambda a: self.sessions.recent_sessions(
+                int(a.get("limit", 10))),
+            "curator_run": lambda a: self.curator.run().summary(),
+            "curator_pin": self._curator_pin,
+        }
+        if name not in handlers:
+            raise ValueError(f"unknown tool: {name}")
+        result = handlers[name](args)
+        # Idle-triggered background loop: every tool call is a chance for the
+        # curator to catch up (cheap due-check, full run only when interval hit).
+        if name != "curator_run":
+            self.curator.maybe_run()
+        return result
+
+    def _project_activate(self, a: dict) -> str:
+        project = a["project"].strip()
+        if a.get("tags"):
+            self.skills.set_project(project, a["tags"])
+        elif self.skills.get_project(project) is None:
+            self.skills.set_project(project, [])
+        self.active_project = project
+        n = len(self.skills.index(project))
+        return f"project '{project}' active — {n} skill(s) in scope"
+
+    def _skill_view(self, a: dict) -> str:
+        skill = self.skills.get(a["name"])
+        if skill is None:
+            return f"skill not found: {a['name']}"
+        return skill.to_markdown()
+
+    def _curator_pin(self, a: dict) -> str:
+        self.curator.pin(a["name"])
+        return f"pinned: {a['name']}"
+
+
+# ---------------------------------------------------------------------------
+# JSON-RPC stdio transport
+# ---------------------------------------------------------------------------
+
+def handle_request(hub: Hub, req: dict) -> dict | None:
+    """Pure request handler — testable without stdio."""
+    rid = req.get("id")
+    method = req.get("method", "")
+
+    if method == "initialize":
+        return _result(rid, {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "oyhub", "version": __version__},
+        })
+    if method in ("notifications/initialized", "notifications/cancelled"):
+        return None  # notifications get no response
+    if method == "tools/list":
+        return _result(rid, {"tools": hub.tool_schemas()})
+    if method == "tools/call":
+        params = req.get("params", {})
+        try:
+            out = hub.call(params.get("name", ""), params.get("arguments", {}) or {})
+            text = out if isinstance(out, str) else json.dumps(out, indent=2)
+            return _result(rid, {"content": [{"type": "text", "text": text}]})
+        except Exception as e:  # tool errors are results, not protocol errors
+            return _result(rid, {
+                "content": [{"type": "text", "text": f"error: {e}"}],
+                "isError": True,
+            })
+    if method == "ping":
+        return _result(rid, {})
+    return _error(rid, -32601, f"method not found: {method}")
+
+
+def _result(rid: Any, result: dict) -> dict:
+    return {"jsonrpc": "2.0", "id": rid, "result": result}
+
+
+def _error(rid: Any, code: int, message: str) -> dict:
+    return {"jsonrpc": "2.0", "id": rid, "error": {"code": code, "message": message}}
+
+
+def serve() -> None:
+    """Blocking stdio loop: one JSON-RPC message per line."""
+    hub = Hub()
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        resp = handle_request(hub, req)
+        if resp is not None:
+            sys.stdout.write(json.dumps(resp) + "\n")
+            sys.stdout.flush()

oyhub/skills.py

@@ -0,0 +1,204 @@
+"""Central skill library with per-project activation.
+
+The fix for skill sprawl:
+  * ONE store on disk (~/.oyhub/skills), each skill a folder with SKILL.md
+    (YAML-ish frontmatter + markdown body). Compatible with the agentskills.io
+    shape used by Claude skills and Hermes.
+  * A compact INDEX (name + description, description hard-capped at 60 chars)
+    is what clients list — full bodies load on demand. This is the Hermes
+    routing trick: cheap index always in context, bodies only when needed.
+  * PROJECT PROFILES map a project to skill tags. Activating a project
+    filters the index to relevant skills only — no more loading your
+    Kubernetes skills while writing a React app.
+  * Usage tracking (last_used, use_count) feeds the curator's staleness policy.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from .config import HubConfig
+from .guard import first_threat
+from .locks import read_json, update_json
+
+DESCRIPTION_LIMIT = 60
+_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+    tags: list[str] = field(default_factory=list)
+    body: str = ""
+
+    def to_markdown(self) -> str:
+        tags = ", ".join(self.tags)
+        return (
+            f"---\nname: {self.name}\ndescription: {self.description}\n"
+            f"tags: [{tags}]\n---\n\n{self.body.strip()}\n"
+        )
+
+
+def _parse_skill_md(text: str, fallback_name: str) -> Skill:
+    meta: dict[str, str] = {}
+    body = text
+    if text.startswith("---"):
+        end = text.find("\n---", 3)
+        if end != -1:
+            for line in text[3:end].strip().splitlines():
+                if ":" in line:
+                    k, v = line.split(":", 1)
+                    meta[k.strip()] = v.strip()
+            body = text[end + 4 :].lstrip("\n")
+    tags = [
+        t.strip()
+        for t in meta.get("tags", "").strip("[]").split(",")
+        if t.strip()
+    ]
+    return Skill(
+        name=meta.get("name", fallback_name),
+        description=meta.get("description", "")[:DESCRIPTION_LIMIT],
+        tags=tags,
+        body=body,
+    )
+
+
+class SkillStore:
+    def __init__(self, cfg: HubConfig):
+        self.cfg = cfg
+        cfg.ensure_dirs()
+
+    # -- CRUD -----------------------------------------------------------------
+
+    def add(self, name: str, description: str, body: str,
+            tags: Optional[list[str]] = None) -> Skill:
+        name = name.strip().lower().replace(" ", "-")
+        if not _NAME_RE.match(name):
+            raise ValueError(
+                f"invalid skill name {name!r}: lowercase-hyphenated, <=64 chars"
+            )
+        description = " ".join(description.split())
+        if len(description) > DESCRIPTION_LIMIT:
+            raise ValueError(
+                f"description is {len(description)} chars; hard cap is "
+                f"{DESCRIPTION_LIMIT}. Anything longer gets truncated in the "
+                f"index and never routes — shorten it."
+            )
+        threat = first_threat(f"{description}\n{body}")
+        if threat:
+            raise ValueError(
+                f"skill blocked: {threat}. Skill bodies load into future "
+                f"context windows, so injection-style content cannot persist."
+            )
+        skill = Skill(name=name, description=description,
+                      tags=sorted(set(tags or [])), body=body)
+        d = self.cfg.skills_dir / name
+        d.mkdir(parents=True, exist_ok=True)
+        (d / "SKILL.md").write_text(skill.to_markdown(), encoding="utf-8")
+        return skill
+
+    def get(self, name: str, track_usage: bool = True) -> Optional[Skill]:
+        path = self.cfg.skills_dir / name / "SKILL.md"
+        if not path.exists():
+            return None
+        if track_usage:
+            self._touch_usage(name)
+        return _parse_skill_md(path.read_text(encoding="utf-8"), name)
+
+    def remove(self, name: str) -> bool:
+        """Archive, never delete (curator invariant: archive is recoverable)."""
+        src = self.cfg.skills_dir / name
+        if not src.exists():
+            return False
+        dst = self.cfg.archive_dir / f"{name}-{int(time.time())}"
+        shutil.move(str(src), str(dst))
+        return True
+
+    def all_names(self) -> list[str]:
+        return sorted(
+            p.name for p in self.cfg.skills_dir.iterdir()
+            if (p / "SKILL.md").exists()
+        )
+
+    # -- index & per-project activation ----------------------------------------
+
+    def index(self, project: Optional[str] = None) -> list[dict]:
+        """Compact index: name + description (+tags). Filtered to the active
+        project's tags when a project is given. This is what goes in context."""
+        wanted = None
+        if project:
+            profile = self.get_project(project)
+            if profile and profile.get("tags"):
+                wanted = set(profile["tags"])
+        out = []
+        for name in self.all_names():
+            skill = self.get(name, track_usage=False)
+            if skill is None:
+                continue
+            if wanted is not None and not (wanted & set(skill.tags)):
+                continue
+            out.append({"name": skill.name,
+                        "description": skill.description[:DESCRIPTION_LIMIT],
+                        "tags": skill.tags})
+        return out
+
+    def search(self, query: str) -> list[dict]:
+        q = query.lower()
+        terms = [t for t in q.split() if t]
+        out = []
+        for name in self.all_names():
+            skill = self.get(name, track_usage=False)
+            if skill is None:
+                continue
+            hay = " ".join([skill.name, skill.description,
+                            " ".join(skill.tags), skill.body]).lower()
+            if all(t in hay for t in terms):
+                out.append({"name": skill.name, "description": skill.description,
+                            "tags": skill.tags})
+        return out
+
+    # -- project profiles -------------------------------------------------------
+
+    def set_project(self, project: str, tags: list[str],
+                    description: str = "") -> dict:
+        profile = {"tags": sorted(set(tags)), "description": description}
+
+        def _set(data: dict) -> dict:
+            data[project] = profile
+            return data
+
+        update_json(self.cfg.projects_file, {}, _set)
+        return profile
+
+    def get_project(self, project: str) -> Optional[dict]:
+        return self._read_projects().get(project)
+
+    def list_projects(self) -> dict:
+        return self._read_projects()
+
+    def _read_projects(self) -> dict:
+        return read_json(self.cfg.projects_file, {})
+
+    # -- usage tracking (feeds the curator) --------------------------------------
+
+    def _usage_file(self) -> Path:
+        return self.cfg.home / "skill_usage.json"
+
+    def usage(self) -> dict:
+        return read_json(self._usage_file(), {})
+
+    def _touch_usage(self, name: str) -> None:
+        def _touch(data: dict) -> dict:
+            rec = data.get(name, {"use_count": 0})
+            rec["use_count"] = rec.get("use_count", 0) + 1
+            rec["last_used"] = time.time()
+            data[name] = rec
+            return data
+
+        update_json(self._usage_file(), {}, _touch)

oyhub-0.2.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: oyhub
+Version: 0.2.0
+Summary: Local agent harness: central skill library, Obsidian + SQLite FTS5 memory, background curator — served over MCP.
+Author-email: Akan Abdireshov <asanovich.02@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Asanovichoff/oyhub
+Project-URL: Repository, https://github.com/Asanovichoff/oyhub
+Project-URL: Issues, https://github.com/Asanovichoff/oyhub/issues
+Keywords: mcp,agent,memory,obsidian,claude,skills,harness
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# OyHub
+
+**A local, always-on agent harness that fixes skill sprawl and context exhaustion.**
+
+Engineers using AI assistants hit two walls: skills scattered across projects with nothing organized in one place, and context windows that fill up and forget everything between sessions. OyHub is an MCP server you install once on your machine — Claude Desktop, Claude Code, and Cursor connect to it and gain:
+
+- **One central skill library** with per-project activation. Skills live in `~/.oyhub/skills` (agentskills.io-compatible `SKILL.md` format). Activate a project and only its relevant skills appear — your Kubernetes skills stay out of your React sessions.
+- **Persistent memory that survives any context window.** Curated facts go to your **Obsidian vault** as plain markdown (human-readable, editable, graph-linked). Full conversation history goes to **SQLite + FTS5** — full-text searchable recall at zero LLM cost. Instead of context running out, the assistant *retrieves* the five messages that matter.
+- **Loop engineering in the background.** A curator loop runs on idle: archives stale skills (never deletes — archive is recoverable), dedupes memory entries, pins protect anything you care about, and every action is logged to a `Curator Log.md` note in your vault so the loop's work stays visible.
+- **Injection-scanned writes.** Memory and skills persist into every future session's context, so anything flowing into them is scanned at write time — instruction-override phrasing and credential-exfil link shapes are refused with a reason. Legitimate engineering content (curl commands, env var names) passes.
+- **Safe under concurrent clients.** Multiple assistants can run OyHub against the same state simultaneously: SQLite runs in WAL mode with busy timeouts, and all shared JSON/markdown writes go through file-locked atomic read-modify-write.
+- **CI/CD + Docker from day one.** GitHub Actions runs lint + tests on a 6-way OS/Python matrix, builds the Docker image, cuts a GitHub release on every version tag, and publishes to PyPI via trusted publishing.
+
+Zero runtime dependencies — Python stdlib only. No API key: the connected assistant is the intelligence; OyHub is the harness.
+
+## Install
+
+```bash
+git clone https://github.com/Asanovichoff/oyhub && cd oyhub
+python3 -m oyhub doctor   # health check
+```
+
+Set where memory lives (your existing Obsidian vault):
+
+```bash
+export OYHUB_VAULT=~/Documents/MyVault
+```
+
+### Connect Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "oyhub": {
+      "command": "python3",
+      "args": ["-m", "oyhub"],
+      "env": {
+        "PYTHONPATH": "/path/to/oyhub",
+        "OYHUB_VAULT": "/Users/you/Documents/MyVault"
+      }
+    }
+  }
+}
+```
+
+> **Note:** Claude Desktop ignores a `cwd` field — `PYTHONPATH` is what makes
+> `python3 -m oyhub` importable. Alternatively, `pip3 install -e /path/to/oyhub`
+> once, then use `"command": "oyhub"` with no `args` or `PYTHONPATH`.
+
+### Connect Claude Code
+
+```bash
+claude mcp add oyhub --env PYTHONPATH=/path/to/oyhub --env OYHUB_VAULT=~/Documents/MyVault -- python3 -m oyhub
+```
+
+Or after `pip3 install -e /path/to/oyhub`: `claude mcp add oyhub -- oyhub`
+
+### Docker
+
+```bash
+docker compose run --rm oyhub          # stdio MCP server
+docker compose run --rm --entrypoint python oyhub -m oyhub doctor
+```
+
+## The tools it exposes
+
+| Tool | What it does |
+|---|---|
+| `project_activate` | Scope skills + memory to a project (creates profile if new) |
+| `skill_add` / `skill_view` / `skill_list` / `skill_search` | Central library; list shows the compact index (60-char descriptions), bodies load on demand |
+| `memory_add` / `memory_snapshot` | Curated memory in your Obsidian vault, project-scoped or global |
+| `session_log` / `session_search` / `session_recent` | FTS5-indexed history: log important turns, search them later with context windows |
+| `curator_run` / `curator_pin` | Run maintenance now; pin skills the curator must never touch |
+
+## A typical day
+
+1. Start a session: Claude calls `project_activate("webapp")` and `memory_snapshot` — it now knows your conventions and this project's facts, without you repeating them.
+2. Work normally. When something worth keeping comes up, Claude calls `memory_add` ("staging DB is read-only") or `skill_add` (a deploy procedure it just worked out).
+3. Next week, in a *fresh* session: "how did we fix that CORS issue?" → `session_search("CORS")` returns the exact exchange. Nothing was lost when the old context window died.
+4. Meanwhile the curator has deduped memory and archived skills untouched for 90 days — check `Curator Log.md` in Obsidian to see what it did.
+
+## Architecture
+
+```
+Claude / Cursor  ──MCP (stdio JSON-RPC)──►  oyhub/server.py
+                                              │
+                    ┌─────────────────────────┼─────────────────────┐
+                    ▼                         ▼                     ▼
+             skills.py                 memory.py               curator.py
+      central library + index    Obsidian vault (curated)   idle-triggered loop:
+      per-project activation     SQLite FTS5 (raw recall)   archive stale, dedupe,
+      usage tracking             frozen-snapshot reads      log actions to vault
+```
+
+Design lineage: the frozen-snapshot memory, 60-char skill index, archive-never-delete curator, and idle-triggered maintenance are patterns from [Hermes Agent](https://github.com/NousResearch/hermes-agent) (Nous Research, MIT), adapted for a keyless MCP harness.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check oyhub tests && pytest tests/ -q   # what CI runs
+```
+
+22 tests, all offline — including concurrency tests (parallel writers, no lost updates) and injection-guard tests. CI matrix: Ubuntu + macOS × Python 3.10–3.12, plus a Docker build + smoke test. Tag `v*` to cut a GitHub release and publish to PyPI (trusted publishing — configure once under PyPI → Publishing).
+
+## Roadmap
+
+- LLM-assisted curation (summarize/consolidate memory notes, improve skill descriptions)
+- Skill import from agentskills.io and Claude skill bundles
+- Session auto-logging middleware
+- Vector search as an optional complement to FTS5
+
+MIT license.

oyhub-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+oyhub/__init__.py,sha256=XsFPfDEGIWRu53QterYpOT0UbfDa0e0C63pG7McpNk8,476
+oyhub/__main__.py,sha256=f1JehGWWoFa8QLVNo38jB9CjrAt2P3v8rhJcc-mauVc,924
+oyhub/config.py,sha256=UhJf0bM45z4xTUO_dQlwVcYzCTbbnEHzR02TWJ00iJ0,1720
+oyhub/curator.py,sha256=75CjR3T9MUE3EN4CdBnKhvH89Ca4QP0C78xpvCXcr5g,5112
+oyhub/guard.py,sha256=pbZ05dfBfj2lRN_4D6h5JYIiGtjD5YajeotrJhnXmVM,2476
+oyhub/locks.py,sha256=7ehYvfjY0HeqhkFbLGn363sXI-FeqCyzCnIpmrTeyKg,2263
+oyhub/memory.py,sha256=k3DqWPVLZ9acK_O3TE-31b0z9p9Od2h5HkmBLvoIYTU,8356
+oyhub/server.py,sha256=WOR84BY4TvW1LXrubx7wjRi7WOIoM9HoRORPH0SXskU,9508
+oyhub/skills.py,sha256=Wdh8j_iT2AzMFKIEsW_gjKNaaFMTvFHPv-LL6G6K03A,7360
+oyhub-0.2.0.dist-info/METADATA,sha256=GJ_K2Voc58Dfyv1jVwq8BBNRbmu0g2ZQUpKVjp76k5E,7470
+oyhub-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+oyhub-0.2.0.dist-info/entry_points.txt,sha256=AnRNpgeRu-RI5lWkIN39t0mIv5ixhjUowBMxi1VOou8,46
+oyhub-0.2.0.dist-info/top_level.txt,sha256=rb8J-s1FcRozPzBTX8k8SEep2RRIfT9K-H_9ip0JW0A,6
+oyhub-0.2.0.dist-info/RECORD,,

oyhub-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

oyhub-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+oyhub = oyhub.__main__:main

oyhub-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+oyhub