contexer 0.1.0__py3-none-any.whl

contexer/__main__.py

@@ -0,0 +1,3 @@
+from contexer.server import main
+
+main()

contexer/server.py

@@ -0,0 +1,78 @@
+import json
+import uuid
+from mcp.server.fastmcp import FastMCP
+from contexer import store
+
+SESSION_ID = str(uuid.uuid4())
+mcp = FastMCP("contexer")
+
+
+@mcp.tool()
+def capture_context(description: str, repo_path: str = "") -> str:
+    """Called at the start of every task. Captures the developer's task description for the given repo."""
+    resolved = store._resolve_repo(repo_path)
+    if not resolved:
+        return "Skipped — repo path not detected."
+    entry_id = store.capture_task(resolved, description, SESSION_ID)
+    if entry_id is None:
+        return "Skipped — does not look like a task description."
+    return f"Captured. id={entry_id}"
+
+
+@mcp.tool()
+def update_context(content: str, repo_path: str = "", subtype: str = "") -> str:
+    """Called when Claude Code makes a significant decision mid-task. The server filters before storing.
+
+    subtype: optional classification for filtered retrieval — architecture | constraint | pattern | convention
+    """
+    resolved = store._resolve_repo(repo_path)
+    if not resolved:
+        return "Skipped — repo path not detected."
+    stored, entry_id = store.update_decision(resolved, content, SESSION_ID, subtype)
+    if stored:
+        return f"Stored. id={entry_id}"
+    return "Filtered — did not meet storage criteria."
+
+
+@mcp.tool()
+def get_context(repo_path: str = "", query: str = "", entry_type: str = "", limit: int = 0) -> str:
+    """Returns stored context for the current repository. Call this when the task requires project context.
+
+    query: optional keyword filter (case-insensitive substring match against decision content).
+    entry_type: optional subtype filter — architecture | constraint | pattern | convention
+    limit: max decisions to return (0 = auto: 25 for filtered queries, 10 for unfiltered overview).
+    """
+    resolved = store._resolve_repo(repo_path)
+    if not resolved:
+        return "No repo path detected."
+    return store.get_context(resolved, query, entry_type, limit)
+
+
+@mcp.tool()
+def bootstrap_context(repo_path: str = "") -> str:
+    """Scans a repo for inferable decisions and gap questions. Present inferred
+    items to the user for confirmation, store confirmed ones via update_context,
+    then ask the gap questions and store each answer."""
+    resolved = store._resolve_repo(repo_path)
+    if not resolved:
+        return json.dumps({"error": "repo path not detected"})
+    return json.dumps(store.bootstrap_scan(resolved), indent=2)
+
+
+@mcp.tool()
+def get_context_for_prompt(repo_path: str = "", prompt: str = "") -> str:
+    """Auto-called by UserPromptSubmit hook on every prompt. Detects rationale/decision
+    questions (why, reason, rationale, decided...) and injects matching stored decisions
+    as additionalContext. Returns empty string for non-rationale prompts — silent no-op."""
+    resolved = store._resolve_repo(repo_path)
+    if not resolved:
+        return ""
+    return store.get_context_for_prompt(resolved, prompt)
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

contexer/store.py

@@ -0,0 +1,739 @@
+import json
+import re
+import tomllib
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+STORE_DIR = Path.home() / ".contexer"
+MAX_ENTRIES = 500
+_UNFILTERED_DISPLAY = 10   # entries shown when no query/type filter applied
+_FILTERED_DISPLAY = 25     # entries shown when a filter is active (caller asked for something specific)
+
+
+def _current_repo_path() -> str:
+    path = STORE_DIR / ".current_repo"
+    if path.exists():
+        return path.read_text().strip()
+    return ""
+
+
+def _resolve_repo(repo_path: str) -> str:
+    if repo_path:
+        return repo_path
+    return _current_repo_path()
+
+def _slug(repo_path: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9_-]", "_", repo_path.strip("/"))
+
+
+def _store_path(repo_path: str) -> Path:
+    STORE_DIR.mkdir(exist_ok=True)
+    return STORE_DIR / f"{_slug(repo_path)}.json"
+
+
+def _load(repo_path: str) -> dict:
+    path = _store_path(repo_path)
+    if path.exists():
+        return json.loads(path.read_text())
+    return {"repo_path": repo_path, "entries": []}
+
+
+def _save(repo_path: str, data: dict) -> None:
+    _store_path(repo_path).write_text(json.dumps(data, indent=2))
+
+
+def _is_novel(content: str, existing: list) -> bool:
+    if not existing:
+        return True
+    tokens = set(content.lower().split())
+    if not tokens:
+        return False
+    for entry in existing:
+        other = set(entry.get("content", "").lower().split())
+        if not other:
+            continue
+        overlap = len(tokens & other) / max(len(tokens), len(other))
+        if overlap > 0.7:
+            return False
+    return True
+
+
+def _passes_filter(content: str, existing: list) -> bool:
+    # Novelty is a prerequisite veto — duplicates are rejected regardless of signal keywords.
+    # Novel content always passes: update_context is only called for significant decisions.
+    decisions_only = [e for e in existing if e["type"] == "decision"]
+    return _is_novel(content, decisions_only)
+
+
+_QUESTION_STARTS = {
+    "what", "how", "why", "when", "where", "who", "which",
+    "is", "are", "can", "does", "do", "will", "would", "could", "should",
+}
+
+def _is_task(content: str) -> bool:
+    stripped = content.strip()
+    words = stripped.lower().split()
+    if len(words) < 5:
+        return False
+    if stripped.endswith("?") and len(words) < 20:
+        return False
+    if words[0] in _QUESTION_STARTS and len(words) < 12:
+        return False
+    return True
+
+
+def capture_task(repo_path: str, description: str, session_id: str) -> str | None:
+    if not _is_task(description):
+        return None
+    data = _load(repo_path)
+    # keep only decisions — one task slot is enough for "last task" context
+    data["entries"] = [e for e in data["entries"] if e["type"] != "task"]
+    entry = {
+        "id": str(uuid.uuid4()),
+        "type": "task",
+        "content": description,
+        "session_id": session_id,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+    data["entries"].append(entry)
+    data["entries"] = data["entries"][-MAX_ENTRIES:]
+    _save(repo_path, data)
+    return entry["id"]
+
+
+def update_decision(repo_path: str, content: str, session_id: str, subtype: str = "") -> tuple[bool, str | None]:
+    data = _load(repo_path)
+    if not _passes_filter(content, data["entries"]):
+        return False, None
+    entry = {
+        "id": str(uuid.uuid4()),
+        "type": "decision",
+        "subtype": subtype,
+        "content": content,
+        "session_id": session_id,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+    data["entries"].append(entry)
+    data["entries"] = data["entries"][-MAX_ENTRIES:]
+    _save(repo_path, data)
+    return True, entry["id"]
+
+
+def _build_bootstrap_context(repo_path: str) -> list[str]:
+    return [
+        "STOP — do not answer the user's request yet.",
+        f"Repo: {repo_path}. No stored context — complete a quick bootstrap first.",
+        "Do this now, before anything else:",
+        "  1. Call the bootstrap_context MCP tool with repo_path='' to get items to confirm.",
+        "  2. Take the first item. State it to the user, ask 'Correct? yes / no / [correction]'. Wait for reply.",
+        "  3. Call update_context to store the confirmed fact. Then move to item 2.",
+        "  4. Repeat until all items are done. Then — and only then — address the user's original request.",
+        "Start by calling bootstrap_context now.",
+    ]
+
+
+def get_session_start_context(repo_path: str) -> dict:
+    data = _load(repo_path)
+    decisions = [e for e in data.get("entries", []) if e["type"] == "decision"]
+    if not decisions:
+        lines = _build_bootstrap_context(repo_path)
+        return {
+            "systemMessage": "Contexer: no context stored — bootstrapping now",
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": "\n".join(lines),
+            },
+        }
+
+    count = len(decisions)
+
+    # Always embed conventions + constraints — these are always-apply rules Claude must
+    # follow from the first task, not discover JIT. Architecture/patterns stay deferred.
+    pre_loaded = [d for d in decisions if d.get("subtype") in ("convention", "constraint")]
+    deferred_count = count - len(pre_loaded)
+
+    # systemMessage: full detail for Claude — rules content + JIT retrieval instruction
+    sys_parts = []
+    if pre_loaded:
+        sys_parts.append("## Project rules — apply to ALL tasks in this repo:")
+        for d in pre_loaded:
+            sys_parts.append(f"- [{d.get('subtype', '')}] {d['content']}")
+    if deferred_count > 0:
+        sys_parts.append(
+            f"{deferred_count} decision(s) stored (architecture/patterns). "
+            "Call get_context BEFORE reading files for any question about architecture, "
+            "design decisions, rationale, or patterns."
+        )
+
+    # additionalContext: single clean status line shown to the user at session start
+    def _pl(n: int, word: str) -> str:
+        return f"{n} {word}" if n == 1 else f"{n} {word}s"
+
+    if pre_loaded and deferred_count > 0:
+        user_line = f"Contexer: loaded {_pl(len(pre_loaded), 'decision')} related to constraint and convention. Remaining {_pl(deferred_count, 'decision')} will be loaded as needed."
+    elif pre_loaded:
+        user_line = f"Contexer: loaded {_pl(len(pre_loaded), 'decision')} related to constraint and convention."
+    else:
+        user_line = f"Contexer: {_pl(count, 'decision')} will be loaded as needed."
+
+    return {
+        "systemMessage": user_line,
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": "\n".join(sys_parts),
+        },
+    }
+
+
+def get_bootstrap_context_prompt(repo_path: str) -> dict:
+    """Fallback for UserPromptSubmit: catches the case where SessionStart bootstrap
+    was skipped (e.g. non-interactive session). Returns empty dict when context exists."""
+    data = _load(repo_path)
+    decisions = [e for e in data.get("entries", []) if e["type"] == "decision"]
+    if decisions:
+        return {}
+    lines = _build_bootstrap_context(repo_path)
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": "\n".join(lines),
+        }
+    }
+
+
+_RATIONALE_WORDS = frozenset({
+    "why", "reason", "rationale", "decision", "decided", "chose", "choice",
+    "motivation", "intent", "reasoning", "background", "justif",
+})
+
+_QUERY_STOP_WORDS = frozenset({
+    "why", "was", "the", "did", "we", "for", "what", "how", "is", "are",
+    "can", "does", "this", "that", "it", "to", "of", "in", "a", "an",
+    "and", "or", "but", "not", "with", "at", "by", "from", "reason",
+    "rationale", "decision", "decided", "chose", "choice", "about", "have",
+    "has", "been", "would", "could", "should", "will", "tell", "explain",
+    "know", "me", "you", "do", "our", "my", "your", "them", "they",
+    "implement", "implemented", "implementation", "use", "using", "used",
+    "build", "built", "create", "created", "add", "added", "make", "made",
+    "just", "here", "there", "when", "then", "than", "also", "get",
+    "into", "which", "who", "where", "what", "that", "its", "been",
+})
+
+
+def get_context_for_prompt(repo_path: str, prompt: str) -> str:
+    """Auto-injected by UserPromptSubmit hook. Returns relevant stored decisions when
+    the prompt is a rationale/decision question. Silent no-op for all other prompts."""
+    data = _load(repo_path)
+    if not data.get("entries"):
+        return ""
+
+    words_raw = [w.strip("?,./!;:\"'()[]") for w in prompt.lower().split()]
+    word_set = set(words_raw)
+
+    if not (word_set & _RATIONALE_WORDS):
+        return ""
+
+    # Extract content keywords: alpha-only, length > 3, not stop words
+    keywords = [
+        w for w in words_raw
+        if len(w) > 3 and w not in _QUERY_STOP_WORDS and w.isalpha()
+    ]
+
+    # Try keywords longest-first (most specific match wins)
+    for kw in sorted(set(keywords), key=len, reverse=True)[:3]:
+        result = get_context(repo_path, query=kw)
+        if "No matching decisions" not in result and "No context stored" not in result:
+            return f"[Contexer: auto-fetched for this question]\n{result}"
+
+    return ""
+
+
+def get_context(repo_path: str, query: str = "", entry_type: str = "", limit: int = 0) -> str:
+    data = _load(repo_path)
+    entries = data.get("entries", [])
+    if not entries:
+        return "No context stored for this repository."
+
+    lines = [f"# Context for {repo_path}\n"]
+
+    if not entry_type:
+        tasks = [e for e in entries if e["type"] == "task"]
+        if tasks:
+            last = tasks[-1]
+            lines.append(f"## Last task ({last['timestamp'][:10]})")
+            lines.append(last["content"])
+            lines.append("")
+
+    decisions = [e for e in entries if e["type"] == "decision"]
+
+    is_filtered = bool(query or entry_type)
+    if entry_type:
+        decisions = [d for d in decisions if d.get("subtype", "") == entry_type]
+
+    if query:
+        q_lower = query.lower()
+        decisions = [d for d in decisions if q_lower in d.get("content", "").lower()]
+
+    display_limit = limit if limit > 0 else (_FILTERED_DISPLAY if is_filtered else _UNFILTERED_DISPLAY)
+
+    if decisions:
+        filter_note = ""
+        if is_filtered:
+            parts = []
+            if query:
+                parts.append(f"query='{query}'")
+            if entry_type:
+                parts.append(f"type='{entry_type}'")
+            filter_note = f" (filtered: {', '.join(parts)})"
+        total = len(decisions)
+        shown = decisions[-display_limit:]
+        if total > display_limit:
+            filter_note += f" — showing {len(shown)} of {total}"
+        lines.append(f"## Decisions and context{filter_note}")
+        for d in shown:
+            subtype_tag = f" [{d['subtype']}]" if d.get("subtype") else ""
+            lines.append(f"- [{d['timestamp'][:10]}]{subtype_tag} {d['content']}")
+        lines.append("")
+    elif is_filtered:
+        parts = []
+        if query:
+            parts.append(f"query='{query}'")
+        if entry_type:
+            parts.append(f"type='{entry_type}'")
+        lines.append(f"No matching decisions found ({', '.join(parts)}).")
+
+    return "\n".join(lines)
+
+
+def _infer_purpose(name: str, readme_summary: str) -> str:
+    """Derive a concrete purpose assumption from project name and README first line."""
+    if readme_summary:
+        return readme_summary
+    if not name:
+        return "Purpose not yet documented"
+    n = name.lower()
+    if any(w in n for w in ["api", "server", "service", "backend"]):
+        return f"Backend API or service (\"{name}\")"
+    if any(w in n for w in ["cli", "tool", "cmd"]):
+        return f"CLI tool (\"{name}\")"
+    if any(w in n for w in ["bot", "agent"]):
+        return f"Bot or agent (\"{name}\")"
+    if any(w in n for w in ["worker", "job", "queue", "task"]):
+        return f"Background worker or job processor (\"{name}\")"
+    if any(w in n for w in ["web", "app", "ui", "front", "dashboard"]):
+        return f"Web app or frontend (\"{name}\")"
+    if any(w in n for w in ["lib", "sdk", "package", "plugin"]):
+        return f"Library or SDK (\"{name}\")"
+    return f"\"{name}\" — type not obvious from name alone"
+
+
+def bootstrap_scan(repo_path: str) -> dict:
+    root = Path(repo_path)
+    data = _load(repo_path)
+    existing = [e for e in data.get("entries", []) if e["type"] == "decision"]
+    inferred: list[str] = []
+    found_files: list[str] = []
+    all_deps: set[str] = set()
+
+    # signals used only for question generation — not stored as inferred facts
+    sig: dict = {
+        "project_name": "",
+        "readme_summary": "",
+        "has_tests": False,
+        "has_ci": False,
+        "has_container": False,
+        "has_infra": False,
+        "has_security_sensitive": False,  # auth or payment deps detected
+        "cloud_detected": "",             # "AWS" | "GCP" | "Azure" | ""
+    }
+
+    def _add(fact: str) -> None:
+        proxy = [{"content": f} for f in inferred]
+        if _is_novel(fact, existing + proxy):
+            inferred.append(fact)
+
+    def _gap(assumption: str, question: str, hint: str) -> dict:
+        return {"assumption": assumption, "question": question, "hint": hint}
+
+    def _has_dep(*names: str) -> bool:
+        return any(n in dep for n in names for dep in all_deps)
+
+    # --- Python ---
+    pyproject_path = root / "pyproject.toml"
+    if pyproject_path.exists():
+        found_files.append("pyproject.toml")
+        try:
+            with open(pyproject_path, "rb") as f:
+                pyp = tomllib.load(f)
+            proj = pyp.get("project", {})
+            name, py_req = proj.get("name", ""), proj.get("requires-python", "")
+            if name:
+                sig["project_name"] = name
+            _add(f"Python project{f' \"{name}\"' if name else ''}{f', requires-python {py_req}' if py_req else ''}")
+            tool = pyp.get("tool", {})
+            if "pytest" in tool:
+                _add("Test framework: pytest")
+                sig["has_tests"] = True
+            if "ruff" in tool:
+                _add("Linting/formatting: ruff")
+            if "mypy" in tool:
+                _add("Type checking: mypy")
+            raw: list[str] = list(proj.get("dependencies", []))
+            for group in pyp.get("dependency-groups", {}).values():
+                raw.extend(d for d in group if isinstance(d, str))
+            for extra in proj.get("optional-dependencies", {}).values():
+                raw.extend(extra)
+            for dep in raw:
+                normalized = re.split(r"[>=<!~\[\s;]", dep.strip())[0].lower().replace("_", "-")
+                all_deps.add(normalized)
+        except Exception:
+            pass
+
+    if (root / "uv.lock").exists():
+        found_files.append("uv.lock")
+        _add("Package manager: uv")
+
+    # --- Node / JS ---
+    pkg_json_path = root / "package.json"
+    if pkg_json_path.exists():
+        found_files.append("package.json")
+        try:
+            pkg = json.loads(pkg_json_path.read_text())
+            name = pkg.get("name", "")
+            if name and not sig["project_name"]:
+                sig["project_name"] = name
+            node_ver = pkg.get("engines", {}).get("node", "")
+            parts = [f"Node.js project \"{name}\"" if name else "Node.js project"]
+            if node_ver:
+                parts.append(f"requires Node {node_ver}")
+            _add(", ".join(parts))
+            mgr = pkg.get("packageManager", "")
+            if mgr:
+                _add(f"Package manager: {mgr.split('@')[0]}")
+            node_deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+            all_deps.update(k.lower() for k in node_deps)
+            if pkg.get("workspaces"):
+                _add("Monorepo: npm/yarn workspaces")
+            if "typescript" in node_deps:
+                _add("Language: TypeScript")
+            for fw in ["next", "nuxt", "remix", "svelte", "react", "vue", "express", "fastify", "hono", "elysia"]:
+                if fw in node_deps:
+                    _add(f"Framework: {fw}")
+                    break
+            test_cmd = pkg.get("scripts", {}).get("test", "")
+            if "jest" in test_cmd or "jest" in node_deps:
+                _add("Test framework: Jest")
+                sig["has_tests"] = True
+            elif "vitest" in test_cmd or "vitest" in node_deps:
+                _add("Test framework: Vitest")
+                sig["has_tests"] = True
+        except Exception:
+            pass
+
+    # --- Go ---
+    if (root / "go.mod").exists():
+        found_files.append("go.mod")
+        try:
+            for line in (root / "go.mod").read_text().splitlines():
+                if line.startswith("module "):
+                    _add(f"Go module: {line.split()[1]}")
+                elif line.startswith("go "):
+                    _add(f"Go version: {line.split()[1]}")
+                    break
+        except Exception:
+            pass
+
+    # --- Rust ---
+    if (root / "Cargo.toml").exists():
+        found_files.append("Cargo.toml")
+        try:
+            with open(root / "Cargo.toml", "rb") as f:
+                c = tomllib.load(f)
+            p = c.get("package", {})
+            if p.get("name") and not sig["project_name"]:
+                sig["project_name"] = p["name"]
+            rust_name = f' "{p["name"]}"' if p.get("name") else ""
+            rust_edition = f', edition {p["edition"]}' if p.get("edition") else ""
+            _add(f"Rust project{rust_name}{rust_edition}")
+        except Exception:
+            pass
+
+    # --- Monorepo ---
+    for mf in ["nx.json", "turbo.json", "lerna.json", "pnpm-workspace.yaml"]:
+        if (root / mf).exists():
+            found_files.append(mf)
+            _add(f"Monorepo: {mf.split('.')[0]} workspace")
+            break
+    if not any("Monorepo" in i for i in inferred):
+        if (root / "packages").is_dir() or (root / "apps").is_dir():
+            _add("Monorepo: packages/ or apps/ directory structure")
+
+    # --- Data layer ---
+    _DB_MAP = {
+        "PostgreSQL": {"psycopg", "psycopg2", "asyncpg", "pg", "postgres", "neon"},
+        "MySQL/MariaDB": {"pymysql", "aiomysql", "mysql2", "mysql"},
+        "MongoDB": {"pymongo", "motor", "mongodb", "mongoose"},
+        "Redis": {"redis", "aioredis", "ioredis"},
+        "SQLite": {"aiosqlite", "better-sqlite3"},
+    }
+    _ORM_DEPS = {"sqlalchemy", "tortoise-orm", "databases", "prisma", "drizzle-orm",
+                 "typeorm", "sequelize", "knex", "mikro-orm"}
+    detected_db = [label for label, names in _DB_MAP.items() if _has_dep(*names)]
+    if detected_db:
+        _add(f"Data store(s): {', '.join(detected_db)}")
+    detected_orm = next((d for d in _ORM_DEPS if _has_dep(d)), None)
+    if detected_orm:
+        _add(f"ORM / query builder: {detected_orm}")
+
+    # --- Auth / payments (security-sensitive signals) ---
+    _AUTH_JWT = {"python-jose", "pyjwt", "jose"}
+    _AUTH_FRAMEWORK = {"passlib", "authlib", "passport", "next-auth", "@auth", "clerk",
+                       "supabase", "firebase-admin", "google-auth", "python-keycloak"}
+    _PAYMENT_DEPS = {"stripe", "braintree"}
+    if _has_dep(*_AUTH_JWT):
+        _add("Auth: JWT-based (pyjwt / python-jose detected)")
+        sig["has_security_sensitive"] = True
+    elif _has_dep(*_AUTH_FRAMEWORK):
+        pkg_found = next((d for d in _AUTH_FRAMEWORK if _has_dep(d)), "unknown")
+        _add(f"Auth: {pkg_found} detected")
+        sig["has_security_sensitive"] = True
+    if _has_dep(*_PAYMENT_DEPS):
+        sig["has_security_sensitive"] = True
+
+    # --- Cloud SDKs ---
+    if _has_dep("boto3", "botocore", "aws-cdk", "@aws-sdk", "aws-lambda"):
+        _add("Cloud: AWS SDK present (boto3 / @aws-sdk)")
+        sig["cloud_detected"] = sig["cloud_detected"] or "AWS"
+    if _has_dep("google-cloud", "@google-cloud", "google-auth"):
+        _add("Cloud: GCP SDK present")
+        sig["cloud_detected"] = sig["cloud_detected"] or "GCP"
+    if _has_dep("azure-", "@azure"):
+        _add("Cloud: Azure SDK present")
+        sig["cloud_detected"] = sig["cloud_detected"] or "Azure"
+
+    # --- External integrations ---
+    _INTEGRATIONS = {
+        "stripe": "Payments: Stripe", "braintree": "Payments: Braintree",
+        "sendgrid": "Email: SendGrid", "resend": "Email: Resend",
+        "twilio": "Messaging: Twilio",
+        "openai": "AI: OpenAI SDK", "anthropic": "AI: Anthropic SDK", "langchain": "AI: LangChain",
+        "celery": "Task queue: Celery", "dramatiq": "Task queue: Dramatiq",
+        "kafka-python": "Messaging: Kafka", "confluent-kafka": "Messaging: Kafka (Confluent)",
+        "pika": "Messaging: RabbitMQ", "aio-pika": "Messaging: RabbitMQ (async)",
+        "elasticsearch-py": "Search: Elasticsearch", "typesense": "Search: Typesense",
+    }
+    for dep, label in _INTEGRATIONS.items():
+        if _has_dep(dep):
+            _add(label)
+
+    # --- CI/CD ---
+    gh_wf = root / ".github" / "workflows"
+    if gh_wf.is_dir():
+        wfs = list(gh_wf.glob("*.yml")) + list(gh_wf.glob("*.yaml"))
+        if wfs:
+            found_files.append(".github/workflows/")
+            _add(f"CI/CD: GitHub Actions ({len(wfs)} workflow file(s))")
+            sig["has_ci"] = True
+    if (root / ".gitlab-ci.yml").exists():
+        found_files.append(".gitlab-ci.yml")
+        _add("CI/CD: GitLab CI")
+        sig["has_ci"] = True
+
+    # --- Docker ---
+    if (root / "Dockerfile").exists():
+        found_files.append("Dockerfile")
+        try:
+            first_from = next(
+                (l.split()[1] for l in (root / "Dockerfile").read_text().splitlines() if l.startswith("FROM")), None
+            )
+            _add(f"Containerized — Dockerfile present{f' (base: {first_from})' if first_from else ''}")
+        except Exception:
+            _add("Containerized — Dockerfile present")
+        sig["has_container"] = True
+    for compose in ["docker-compose.yml", "docker-compose.yaml"]:
+        if (root / compose).exists():
+            found_files.append(compose)
+            _add("Local dev: docker-compose present")
+            break
+
+    # --- Linting / formatting ---
+    eslint_files = [".eslintrc", ".eslintrc.js", ".eslintrc.json", ".eslintrc.cjs",
+                    "eslint.config.js", "eslint.config.mjs", "eslint.config.cjs"]
+    if any((root / f).exists() for f in eslint_files):
+        found_files.append(".eslintrc*")
+        _add("Linting: ESLint")
+    prettier_files = [".prettierrc", ".prettierrc.json", ".prettierrc.js",
+                      ".prettierrc.cjs", "prettier.config.js"]
+    if any((root / f).exists() for f in prettier_files):
+        found_files.append(".prettierrc*")
+        _add("Formatting: Prettier")
+    if (root / "ruff.toml").exists():
+        found_files.append("ruff.toml")
+        _add("Linting/formatting: ruff (ruff.toml)")
+    if (root / "pytest.ini").exists():
+        found_files.append("pytest.ini")
+        _add("Test framework: pytest (pytest.ini)")
+        sig["has_tests"] = True
+
+    # --- Infrastructure ---
+    if list(root.glob("*.tf")) or (root / "terraform").is_dir():
+        _add("Infrastructure as code: Terraform")
+        sig["has_infra"] = True
+    if any((root / d).is_dir() for d in ["k8s", "kubernetes", "helm"]):
+        _add("Deployment: Kubernetes (manifests or Helm charts present)")
+        sig["has_infra"] = True
+
+    # --- Architecture signals ---
+    src = root / "src"
+    if src.is_dir():
+        layers = [d for d in ["api", "services", "models", "controllers", "middleware", "handlers", "repositories"]
+                  if (src / d).is_dir()]
+        if layers:
+            layer_str = ", ".join(layers[:3]) + ("..." if len(layers) > 3 else "")
+            _add(f"Architecture: layered structure detected (src/{layer_str})")
+
+    # --- README summary (for purpose inference) ---
+    readme = root / "README.md"
+    if readme.exists():
+        found_files.append("README.md")
+        try:
+            lines = [l.strip() for l in readme.read_text().splitlines()
+                     if l.strip() and not l.startswith("#")]
+            if lines:
+                sig["readme_summary"] = lines[0][:120]
+        except Exception:
+            pass
+    for cf in ["CLAUDE.md", ".cursorrules"]:
+        if (root / cf).exists():
+            found_files.append(cf)
+
+    # --- Primary stack detection for stack-aware hints ---
+    primary_stack = (
+        "python" if any("Python" in i for i in inferred) else
+        "node"   if any("Node.js" in i or "TypeScript" in i for i in inferred) else
+        "go"     if any("Go module" in i or "Go version" in i for i in inferred) else
+        "rust"   if any("Rust" in i for i in inferred) else
+        "generic"
+    )
+
+    def _test_hint() -> str:
+        if primary_stack == "python":
+            return "e.g. pytest with fixtures and coverage threshold; no mocking external calls in unit tests"
+        if primary_stack == "node":
+            return "e.g. Jest or Vitest; 80% coverage threshold; no real HTTP calls in unit tests"
+        if primary_stack == "go":
+            return "e.g. go test, table-driven tests; benchmarks for hot paths"
+        if primary_stack == "rust":
+            return "e.g. cargo test; #[cfg(test)] modules; integration tests in tests/"
+        return "e.g. unit tests, integration tests, coverage threshold"
+
+    def _exclusions_hint() -> str:
+        if primary_stack == "python":
+            return "e.g. 'no requests, use httpx'; 'no Flask, FastAPI only'; 'always type-annotate public APIs'"
+        if primary_stack == "node":
+            return "e.g. 'no CommonJS, ESM only'; 'no lodash, use native'; 'no class-based components'"
+        if primary_stack == "go":
+            return "e.g. 'no global state'; 'always wrap errors with fmt.Errorf'; 'no init() functions'"
+        if primary_stack == "rust":
+            return "e.g. 'no unwrap() in production code'; 'async with tokio only'; 'no unsafe blocks'"
+        return "e.g. specific libraries to avoid, patterns to always follow, things that must never happen"
+
+    def _constraints_hint() -> str:
+        if sig["has_security_sensitive"] and sig["cloud_detected"]:
+            return f"e.g. GDPR / PCI-DSS compliance; {sig['cloud_detected']} cost ceiling; latency SLA"
+        if sig["has_security_sensitive"]:
+            return "e.g. GDPR, PCI-DSS, SOC2, HIPAA; audit logging requirements; data residency"
+        if sig["cloud_detected"]:
+            return f"e.g. {sig['cloud_detected']} cost ceiling; latency SLA; multi-region requirements"
+        return "e.g. <100ms p99 latency; 1M+ concurrent users; GDPR; monthly cost ceiling"
+
+    # --- Intent gaps: all conditional on signals ---
+    gaps: list[dict] = []
+
+    # Purpose — always: can never be inferred from code
+    name = sig["project_name"]
+    gaps.append(_gap(
+        assumption=_infer_purpose(name, sig["readme_summary"]),
+        question="What does this repo do and who uses it?",
+        hint=(
+            f"e.g. what {name} is for and who uses it"
+            if name else
+            "e.g. 'REST API for internal task management, used by 3 frontend apps'"
+        ),
+    ))
+
+    # Tests — only if no test framework detected
+    if not sig["has_tests"]:
+        gaps.append(_gap(
+            assumption="No automated test framework detected",
+            question="Is automated testing in scope?",
+            hint=_test_hint(),
+        ))
+
+    # CI — only if no CI config found
+    if not sig["has_ci"]:
+        gaps.append(_gap(
+            assumption="No CI/CD config found in this repo",
+            question="Is there a build or deploy pipeline, or is one planned?",
+            hint="e.g. GitHub Actions, GitLab CI, CircleCI; or: manual deploys, not needed yet",
+        ))
+
+    # Deployment — only if no container or infra config
+    if not sig["has_container"] and not sig["has_infra"]:
+        gaps.append(_gap(
+            assumption="No container or infra config found — deployment target unclear",
+            question="Where does this run, or is it local-only?",
+            hint="e.g. containerized VPS, serverless function, internal CLI, local-only tool, not deployed yet",
+        ))
+
+    # Cloud SDK but no deploy config — probably in a separate repo
+    if sig["cloud_detected"] and not sig["has_container"] and not sig["has_infra"]:
+        gaps.append(_gap(
+            assumption=f"{sig['cloud_detected']} SDK detected but no deploy config found here",
+            question=f"Is the {sig['cloud_detected']} deploy config in a separate repo?",
+            hint="e.g. separate infra repo, serverless framework config, or not yet set up",
+        ))
+
+    # Compliance — only if auth or payment deps detected
+    if sig["has_security_sensitive"]:
+        gaps.append(_gap(
+            assumption="Auth or payment handling detected — compliance requirements unknown",
+            question="Any compliance or security requirements given the auth/payment handling?",
+            hint="e.g. GDPR, PCI-DSS, SOC2, HIPAA; internal security policy; audit logging; data residency",
+        ))
+
+    # Team conventions — only if architecture signals suggest a team wrote this
+    has_team_signals = (
+        any("Architecture" in i or "layered" in i for i in inferred) or
+        len(inferred) > 5
+    )
+    if has_team_signals:
+        gaps.append(_gap(
+            assumption="Team conventions not captured in config files",
+            question="Any branching model, PR process, or unwritten norms beyond what's in config files?",
+            hint="e.g. trunk-based vs feature branches; PR review requirements; who owns which area",
+        ))
+
+    # Exclusions — only if dep tree suggests architectural choices were made
+    has_dep_choices = len(all_deps) > 5 or bool(detected_orm) or len(detected_db) > 0
+    if has_dep_choices:
+        gaps.append(_gap(
+            assumption="No known intentional library exclusions or architectural mandates",
+            question="Any libraries or patterns that are intentionally excluded or always required?",
+            hint=_exclusions_hint(),
+        ))
+
+    # Constraints — only if production signals exist
+    has_production_signals = (
+        sig["has_security_sensitive"] or sig["cloud_detected"] or
+        sig["has_infra"] or sig["has_container"]
+    )
+    if has_production_signals:
+        gaps.append(_gap(
+            assumption="No known performance, scale, or compliance constraints",
+            question="Any constraints that shape technical decisions?",
+            hint=_constraints_hint(),
+        ))
+
+    return {"inferred": inferred, "gaps": gaps, "existing_context_files": found_files}

contexer-0.1.0.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: contexer
+Version: 0.1.0
+Summary: MCP server that captures and retrieves architectural decisions and context for Claude Code sessions
+Project-URL: Homepage, https://github.com/bhargavamin/contexer
+Project-URL: Repository, https://github.com/bhargavamin/contexer
+Project-URL: Issues, https://github.com/bhargavamin/contexer/issues
+Author-email: Bhargav Amin <devops.techpro@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,context,decisions,llm,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: mcp>=1.9.4
+Description-Content-Type: text/markdown
+
+# Contexer
+
+Contexer is a lightweight MCP server for Claude Code that automatically captures decisions made during coding sessions and surfaces them at the start of every future session — so Claude never starts blind.
+
+## The problem
+
+Every Claude Code session starts with no memory of the previous one. CLAUDE.md files require manual maintenance and go stale. When Claude works autonomously, the reasoning behind decisions disappears when the session ends. Teams end up re-explaining the same constraints, conventions, and architecture choices every time.
+
+Contexer solves this by capturing decisions as they happen — silently, automatically, in the background — and replaying them as project rules at session start.
+
+---
+
+## Quick start
+
+Install takes under two minutes. See **[docs/install.md](docs/install.md)** for full steps, verification, and uninstall.
+For hooks, tool internals, filter logic, and storage layout see **[docs/architecture.md](docs/architecture.md)**.
+
+**Plugin (recommended):**
+
+```
+/plugin marketplace add bhargavamin/contexer
+/plugin install contexer@contexer
+/reload-plugins
+```
+
+**Manual:**
+
+```bash
+git clone git@github.com:bhargavamin/contexer.git ~/tools/contexer
+bash ~/tools/contexer/scripts/install.sh
+```
+
+After install, **open a new Claude Code session in any repo.** If no context exists, Claude will automatically run a bootstrap to capture your first decisions. If context exists, all constraints and conventions are injected at session start.
+
+---
+
+## How it works
+
+You work normally. Contexer runs in the background via Claude Code hooks.
+
+```
+Session opens
+  └─▶ All conventions + constraints injected as project rules
+      Architecture/pattern decisions available on demand (JIT)
+      First session with no context → bootstrap runs automatically
+
+You type a prompt
+  └─▶ Your first message is stored as the current task description
+  └─▶ "Why/reason/rationale/decided" questions auto-fetch matching decisions
+
+Claude works
+  └─▶ Calls get_context when it needs architecture or pattern context
+  └─▶ Calls update_context when it makes a significant decision
+
+Context window nears limit
+  └─▶ Claude is reminded to save any unsaved decisions before compaction
+  └─▶ After compaction, full context is reloaded automatically
+```
+
+**You never call any tool directly.** Claude handles all tool calls. If Claude misses something, say *"store that decision"* and it will call `update_context` immediately.
+
+---
+
+## Decision types
+
+Every stored decision has a `subtype` that controls when and how it is surfaced.
+
+| Subtype | What it captures | Injected at session start? |
+|---|---|---|
+| `constraint` | Rules that must always apply — "never commit untested code" | Yes — always |
+| `convention` | Team or project standards — "use uv not pip", "conventional commits" | Yes — always |
+| `architecture` | Structural decisions — "chose FastMCP over low-level mcp.Server" | No — fetched on demand |
+| `pattern` | Recurring implementation approaches — "plain dicts as function boundaries" | No — fetched on demand |
+
+Constraints and conventions are injected directly at every session start because they apply to every task. Architecture and pattern decisions are large and task-specific — Claude fetches them just-in-time when the task requires them.
+
+---
+
+## Managing decisions
+
+All operations use natural language. Claude translates them into the right tool call.
+
+### Store a decision
+
+```
+"store that as a constraint"
+"save this as a convention: always use uv not pip"
+"remember this architecture decision"
+```
+
+Claude calls `update_context` with the content and the appropriate subtype. The server applies a novelty filter before storing — content with more than 70% token overlap with an existing decision is silently discarded as a duplicate.
+
+> **Note:** Your first prompt each session is automatically stored as the *task description* — not as a decision or constraint. If you open a session with an instruction like *"always update docs before committing"*, it is captured as the task, not stored as a constraint. To store it as a constraint, either complete the turn (Claude will call `update_context` at the end) or explicitly say *"store that as a constraint"*.
+
+### Query decisions
+
+```
+"show me all constraints"
+"what decisions did we make about postgres?"
+"show everything stored for this repo"
+```
+
+| Example call | What it returns |
+|---|---|
+| `get_context()` | Latest 10 decisions — overview |
+| `get_context(entry_type="constraint")` | Up to 25 constraints |
+| `get_context(query="postgres")` | Up to 25 decisions matching "postgres" |
+| `get_context(limit=50)` | Up to 50 decisions |
+
+### Update a decision
+
+```
+"update the uv decision — we switched back to pip"
+"correct the constraint about commit format"
+```
+
+Claude calls `update_context` with the revised content. The old entry is not removed — a new entry is added alongside it. If the revised content is too similar to the original (>70% token overlap), it will be filtered as a duplicate. Rephrase it to include what changed.
+
+### Remove a decision
+
+```
+"delete the postgres decision"
+"remove all outdated constraints"
+```
+
+Claude reads `~/.contexer/<repo_slug>.json` and removes the matching entry directly. The file is plain JSON — you can also edit or prune it manually at any time.
+
+---
+
+## Tools reference
+
+| Tool | Triggered by | What it does |
+|---|---|---|
+| `capture_context` | `UserPromptSubmit` hook — once per session | Stores the first prompt as the task description |
+| `update_context` | Claude, mid-task | Nominates a decision; server filters before storing |
+| `get_context` | Claude, on demand | Returns stored decisions — filtered by keyword or subtype |
+| `get_context_for_prompt` | `UserPromptSubmit` hook — every prompt | Detects rationale questions and auto-injects matching decisions |
+| `bootstrap_context` | Claude, first session with no context | Scans repo stack for inferable decisions; surfaces gap questions |
+
+---
+
+## Storage
+
+Decisions are stored locally at `~/.contexer/<repo_slug>.json` — one file per repo, capped at 500 entries. No cloud, no database, no accounts.
+
+Each entry contains:
+
+| Field | Values |
+|---|---|
+| `id` | UUID |
+| `type` | `task` or `decision` |
+| `subtype` | `architecture` \| `constraint` \| `pattern` \| `convention` |
+| `content` | The full decision text |
+| `session_id` | UUID for the session that created it |
+| `timestamp` | ISO 8601 UTC |
+
+Inspect the store at any time:
+
+```bash
+cat ~/.contexer/<repo_slug>.json
+```
+
+---
+
+## Troubleshooting
+
+**Claude isn't storing decisions automatically.**
+Claude calls `update_context` at the end of significant decisions, not continuously. If something specific was missed, say *"store that decision"* and Claude will call it immediately.
+
+**A decision was stored but later ignored.**
+Constraints and conventions are injected at session start. If you added a new constraint mid-session, it will appear from the next session onward.
+
+**A decision is outdated or wrong.**
+Say *"delete the X decision"* or edit `~/.contexer/<repo_slug>.json` directly and remove the entry.
+
+**The novelty filter rejected a new decision.**
+If the content is too similar to an existing one (>70% token overlap), it is silently discarded. Rephrase it to be more specific, or remove the old entry first.
+
+**No context was injected at session start.**
+If no decisions are stored for the repo, the bootstrap flow runs instead. Complete bootstrap once and all future sessions will have context.
+
+---
+
+## License
+
+MIT

contexer-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+contexer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+contexer/__main__.py,sha256=2ukUX0-kicHLiK9MT2Y02r5ZSaI6_pwQd-jpmu5rgXw,41
+contexer/server.py,sha256=kfdETEvvTzeBr9SZzaOMzTDZUSbS17WG4ci4c6LAw2A,3034
+contexer/store.py,sha256=UNUPkWkI3sflSvoJDIccNvf0o-i4aD53eGokYIUrlj4,30686
+contexer-0.1.0.dist-info/METADATA,sha256=wCLYEwT0oDeHzZ-WhVBUNV65oX0PrA8woxJTqkH7Vss,8488
+contexer-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+contexer-0.1.0.dist-info/entry_points.txt,sha256=MClLqvDhWe4p8kmVgwl9o7heDyx6wNep-TnPG-AxF50,50
+contexer-0.1.0.dist-info/licenses/LICENSE,sha256=WDlQ0ISzY2yN46w9zx-kcr6V8jTDB0RqqW-iRY85VDk,1069
+contexer-0.1.0.dist-info/RECORD,,

contexer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

contexer-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+contexer = contexer.server:main

contexer-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bhargav Amin
+
+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.