fernme 0.3.0__py3-none-any.whl

fernme/__init__.py

@@ -0,0 +1,2 @@
+"""FERNme — Fuzzy-Edged Recall Network. A user-owned, near-zero-LLM Hebbian memory layer for AI agents (web today; desktop/mobile on the roadmap)."""
+__version__ = "0.3.0"

fernme/api/mcp_server.py

@@ -0,0 +1,80 @@
+"""MCP server exposing FERN as agent tools, so any MCP-capable agent (incl.
+Claude) can give a user persistent, glass-box memory. Run: python -m fern.api.mcp_server
+Requires: pip install mcp"""
+from __future__ import annotations
+import os
+from ..service import FernService
+
+svc = FernService()  # default: $FERNME_DB or ~/.fernme/fernme.db
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except Exception as e:  # pragma: no cover
+    FastMCP = None
+
+if FastMCP is not None:
+    mcp = FastMCP("fernme")
+
+    @mcp.tool()
+    def remember(site: str, user: str, type: str = "note", tags: list[str] = [],
+                 text: str = "", source: str = "stated", glosses: dict = {},
+                 ts: float = 0.0) -> dict:
+        """Record an interaction/preference for a user on a site (consent required).
+
+        tags:    namespaced 'ns:value' tokens, e.g. 'pref:concise', 'topic:python',
+                 '!likes:dairy' (leading '!' = a dislike). Prefer SPECIFIC tags.
+        text:    the sentence this came from. Stored as free context (no token
+                 cost) so a bare tag isn't ambiguous later.
+        source:  'stated' (the user said it) or 'inferred' (you guessed it).
+                 Inferred never silently overrides stated; conflicts return a
+                 'questions' list to ask the user.
+        glosses: optional {tag: one-line meaning}. Emit these as a byproduct of
+                 your reply (a few tokens, no separate call). Missing ones fall
+                 back to a deterministic namespace template (0 tokens).
+        Returns stored attrs, plus 'questions'/'superseded' when curation is on."""
+        payload = {"tags": tags, "source": source}
+        if text:
+            payload["text"] = text
+        if glosses:
+            payload["glosses"] = glosses
+        return svc.observe(site, user, type, payload, ts)
+
+    @mcp.tool()
+    def recall_glossary(site: str, user: str) -> dict:
+        """What each remembered tag MEANS: {tag: {gloss, context}}. Context is the
+        sentence it came from; gloss is the supplied or templated one-liner."""
+        return svc.glossary(site, user)
+
+    @mcp.tool()
+    def grant_consent(site: str, user: str, granted: bool = True) -> dict:
+        """Grant or withdraw a user's consent to be remembered on a site."""
+        return svc.consent(site, user, granted)
+
+    @mcp.tool()
+    def recall_card(site: str, user: str, context: list[str] = [], now: float = 0.0) -> dict:
+        """Get the token-minimal memory card for a user (what to inject into the prompt)."""
+        return svc.card(site, user, context, now)
+
+    @mcp.tool()
+    def recall_events(site: str, user: str, contains: str = "", limit: int = 20) -> list:
+        """Open the Cabinet: search a user's raw interaction history for specifics."""
+        return svc.recall(site, user, contains=contains or None, limit=limit)
+
+    @mcp.tool()
+    def edit_memory(site: str, user: str, attr: str, weight: float) -> dict:
+        """Glass-box override of a single preference (locked, never decays)."""
+        return svc.edit(site, user, attr, weight)
+
+    @mcp.tool()
+    def forget_me(site: str, user: str) -> dict:
+        """Delete everything stored about a user on a site (right to be forgotten)."""
+        return svc.delete(site, user)
+
+    def main():
+        mcp.run()
+else:
+    def main():
+        raise SystemExit("Install the 'mcp' package: pip install mcp")
+
+if __name__ == "__main__":
+    main()

fernme/api/rest.py

@@ -0,0 +1,125 @@
+"""FastAPI REST interface for FERN v1. Run:
+  uvicorn fern.api.rest:app --port 8077
+Every endpoint is consent-gated by the service layer."""
+from __future__ import annotations
+import os
+from typing import List, Optional, Any, Dict
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from ..service import FernService, ConsentError
+
+svc = FernService()  # default: $FERNME_DB or ~/.fernme/fernme.db
+app = FastAPI(title="FERN Memory API", version="1.0")
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
+_UI = os.path.join(os.path.dirname(__file__), "..", "web", "glassbox.html")
+_GRAPH_UI = os.path.join(os.path.dirname(__file__), "..", "web", "graph.html")
+_API_KEY = os.environ.get("FERNME_API_KEY")  # if set, all data routes require X-API-Key
+_OPEN = {"/health", "/ui", "/docs", "/redoc", "/openapi.json", "/docs/oauth2-redirect"}
+
+
+@app.middleware("http")
+async def _auth(request, call_next):
+    if _API_KEY and request.url.path not in _OPEN:
+        if request.headers.get("x-api-key") != _API_KEY:
+            return JSONResponse({"detail": "invalid or missing X-API-Key"}, status_code=401)
+    return await call_next(request)
+
+
+@app.get("/ui")
+def ui():
+    return FileResponse(_UI)
+
+class GraphIn(BaseModel):
+    site: str; user: Optional[str] = None
+
+class WhyIn(BaseModel):
+    site: str; user: str; attr: str
+
+class MemoryGraphIn(BaseModel):
+    person: str
+
+@app.get("/graph")
+def graph_ui():
+    return FileResponse(_GRAPH_UI)
+
+@app.post("/graph-data")
+def graph_data(b: GraphIn):
+    return _guard(svc.graph, b.site, b.user)
+
+@app.post("/memory-graph")
+def memory_graph(b: MemoryGraphIn):
+    return _guard(svc.memory_graph, b.person)
+
+
+class ConsentIn(BaseModel):
+    site: str; user: str; granted: bool = True; ts: float = 0.0
+
+class ObserveIn(BaseModel):
+    site: str; user: str; type: str = "purchase"; payload: Dict[str, Any] = {}; ts: float = 0.0
+
+class NumericIn(BaseModel):
+    site: str; user: str; key: str; value: Any
+
+class CardIn(BaseModel):
+    site: str; user: str; context: List[str] = []; now: float = 0.0
+
+class EditIn(BaseModel):
+    site: str; user: str; attr: str; weight: float
+
+class RecallIn(BaseModel):
+    site: str; user: str; type: Optional[str] = None; contains: Optional[str] = None; limit: int = 20
+
+class UserRef(BaseModel):
+    site: str; user: str
+
+class TriggersIn(BaseModel):
+    site: str; user: str; now: float = 0.0
+
+
+def _guard(fn, *a, **k):
+    try:
+        return fn(*a, **k)
+    except ConsentError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+
+
+@app.get("/health")
+def health(): return {"ok": True, "service": "fern", "version": "1.0"}
+
+@app.post("/consent")
+def consent(b: ConsentIn): return svc.consent(b.site, b.user, b.granted, b.ts)
+
+@app.post("/observe")
+def observe(b: ObserveIn): return _guard(svc.observe, b.site, b.user, b.type, b.payload, b.ts)
+
+@app.post("/numeric")
+def numeric(b: NumericIn): return _guard(svc.set_numeric, b.site, b.user, b.key, b.value)
+
+@app.post("/card")
+def card(b: CardIn): return _guard(svc.card, b.site, b.user, b.context, b.now)
+
+@app.post("/defaults")
+def defaults(b: CardIn): return _guard(svc.defaults, b.site, b.user, b.now)
+
+@app.post("/recall")
+def recall(b: RecallIn): return _guard(svc.recall, b.site, b.user, b.type, b.contains, b.limit)
+
+@app.post("/edit")
+def edit(b: EditIn): return _guard(svc.edit, b.site, b.user, b.attr, b.weight)
+
+@app.post("/why")
+def why(b: WhyIn): return _guard(svc.why, b.site, b.user, b.attr)
+
+@app.post("/export")
+def export(b: UserRef): return _guard(svc.export, b.site, b.user)
+
+@app.post("/delete")
+def delete(b: UserRef): return svc.delete(b.site, b.user)
+
+@app.post("/triggers")
+def triggers(b: TriggersIn): return _guard(svc.triggers, b.site, b.user, b.now)
+
+@app.post("/prior_refresh")
+def prior_refresh(b: UserRef): return svc.prior_refresh(b.site)

fernme/audit.py

@@ -0,0 +1,28 @@
+"""Verifiable data ownership (#4) — a tamper-evident, user-keyed audit log.
+
+Every action is recorded as a link in an HMAC hash chain: each entry's hash binds
+the previous hash + the action, keyed by the user's secret. Anyone holding the key
+can replay the chain and detect if a single entry was altered, inserted, or
+removed. (Production upgrade: per-user asymmetric keys so the USER signs and the
+server can't forge — same chain, stronger ownership.)"""
+from __future__ import annotations
+import hmac, hashlib, json
+
+GENESIS = "GENESIS"
+
+
+def entry_hash(key: bytes, prev_hash: str, seq: int, ts: float,
+               action: str, detail: dict) -> str:
+    msg = f"{prev_hash}|{seq}|{ts}|{action}|{json.dumps(detail, sort_keys=True)}"
+    return hmac.new(key, msg.encode(), hashlib.sha256).hexdigest()
+
+
+def verify(entries, key: bytes):
+    """Replay the chain. Returns (ok, broken_seq)."""
+    prev = GENESIS
+    for e in entries:
+        h = entry_hash(key, prev, e["seq"], e["ts"], e["action"], e["detail"])
+        if not hmac.compare_digest(h, e["hash"]):
+            return False, e["seq"]
+        prev = e["hash"]
+    return True, None

fernme/auth.py

@@ -0,0 +1,64 @@
+"""Sign-in -> supernode linking. The supernode is built by the USER signing in
+with their FERN account (the consent moment), never by behind-the-back matching.
+
+This module is provider-agnostic: it verifies a signed identity token and maps it
+to a stable person_id, then links the current site's local user into that person's
+supernode. A MockProvider is included so the flow is testable end-to-end without a
+real IdP; a real Google/GitHub OIDC verifier drops in behind the same interface."""
+from __future__ import annotations
+import hmac, hashlib, json, base64, time
+from typing import Optional
+
+
+def _b64(d: bytes) -> str: return base64.urlsafe_b64encode(d).decode().rstrip("=")
+def _unb64(s: str) -> bytes: return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+class MockProvider:
+    """Stand-in identity provider: issues and verifies HMAC-signed tokens. Mirrors
+    the contract of a real OIDC id_token (issuer, subject, expiry, signature)."""
+    def __init__(self, secret: bytes = b"mock-idp-secret", issuer: str = "mock-idp"):
+        self.secret = secret; self.issuer = issuer
+
+    def issue(self, subject: str, email: str = "", ttl: int = 3600) -> str:
+        body = {"iss": self.issuer, "sub": subject, "email": email,
+                "exp": int(time.time()) + ttl}
+        payload = _b64(json.dumps(body, sort_keys=True).encode())
+        sig = _b64(hmac.new(self.secret, payload.encode(), hashlib.sha256).digest())
+        return f"{payload}.{sig}"
+
+    def verify(self, token: str) -> dict:
+        try:
+            payload, sig = token.split(".")
+        except ValueError:
+            raise AuthError("malformed token")
+        expect = _b64(hmac.new(self.secret, payload.encode(), hashlib.sha256).digest())
+        if not hmac.compare_digest(sig, expect):
+            raise AuthError("bad signature")              # tamper / forgery
+        body = json.loads(_unb64(payload))
+        if body.get("exp", 0) < time.time():
+            raise AuthError("token expired")
+        if body.get("iss") != self.issuer:
+            raise AuthError("untrusted issuer")
+        return body
+
+
+class AuthError(RuntimeError):
+    pass
+
+
+def person_id_for(claims: dict) -> str:
+    """Stable, opaque person id from verified claims (issuer+subject). Never the
+    raw email -> identities aren't linkable by guessing an address."""
+    raw = f"{claims['iss']}:{claims['sub']}".encode()
+    return "person:" + hashlib.sha256(raw).hexdigest()[:16]
+
+
+def sign_in_and_link(service, provider, token: str, site: str, local_user: str) -> dict:
+    """The whole handshake: verify the token, derive the person, link THIS site's
+    local user into their supernode. Consent is implicit in the user choosing to
+    sign in with their FERN identity here."""
+    claims = provider.verify(token)               # raises AuthError on tamper/expiry
+    person = person_id_for(claims)
+    service.link_identity(person, site, local_user)
+    return {"person": person, "linked": service.store.list_identities(person)}

fernme/capture/__init__.py

@@ -0,0 +1,69 @@
+"""fernme.capture — the pluggable *perception* layer above the 0-LLM engine.
+
+Pick how memory gets written without touching the engine. Three adapters, each
+with an honest token-cost label:
+
+    signal   structured events -> rules            0 tokens
+    local    text -> local rules or local model    0 API tokens (your CPU/GPU)
+    agent    host agent emits a tag line           ~20-40 tokens, no extra call
+
+Typical use:
+
+    from fernme.service import FernService
+    from fernme.store.sqlite_store import SQLiteStore
+    from fernme.capture import load_pipeline
+
+    svc = FernService(store=SQLiteStore("memory.db"))
+    svc.store.set_consent("demo.com", "elena", True)
+    pipe = load_pipeline(svc, "demo.com", "elena", "fern.toml")
+    pipe.ingest({"kind": "chat", "text": "keep it concise",
+                 "tags": ["pref:concise"]})
+"""
+from __future__ import annotations
+from typing import Dict, List
+
+from .base import BaseAdapter
+from .signal_hooks import SignalAdapter
+from .local_tagger import LocalTaggerAdapter
+from .agent_byproduct import AgentByproductAdapter
+from .config import load_config, write_config, default_config, VALID
+from .pipeline import CapturePipeline
+
+REGISTRY = {
+    "signal": SignalAdapter,
+    "local": LocalTaggerAdapter,
+    "agent": AgentByproductAdapter,
+}
+
+
+def build_adapters(cfg: Dict) -> List[BaseAdapter]:
+    """Instantiate the active adapters from a parsed config dict."""
+    out: List[BaseAdapter] = []
+    for name in cfg.get("active", []):
+        cls = REGISTRY.get(name)
+        if cls is None:
+            continue
+        opts = dict(cfg.get(name, {}))
+        if name == "local":
+            out.append(LocalTaggerAdapter(
+                mode=opts.get("mode", "rules"),
+                model=opts.get("model", "hermes3"),
+                endpoint=opts.get("endpoint", "http://localhost:11434")))
+        elif name == "agent":
+            out.append(AgentByproductAdapter(marker=opts.get("marker", "FERN_TAGS:")))
+        else:
+            out.append(cls())
+    return out
+
+
+def load_pipeline(svc, site: str, user: str, path: str = "fern.toml") -> CapturePipeline:
+    cfg = load_config(path)
+    return CapturePipeline(svc, site, user, build_adapters(cfg))
+
+
+__all__ = [
+    "BaseAdapter", "SignalAdapter", "LocalTaggerAdapter", "AgentByproductAdapter",
+    "CapturePipeline", "REGISTRY", "VALID",
+    "build_adapters", "load_pipeline", "load_config", "write_config",
+    "default_config",
+]

fernme/capture/agent_byproduct.py

@@ -0,0 +1,43 @@
+"""agent — near-zero capture by piggybacking on the host agent's own reply.
+
+The realistic FERNme path when you are *already* talking to an LLM agent
+(Claude Cowork, Codex, ...). The agent appends a tiny tag line as a byproduct of
+the answer it is generating anyway — there is NO separate model call. The only
+cost is the handful of extra output tokens of the tag line itself (~20-40).
+
+This adapter does not call any model. It just parses the marker line the agent
+emitted out of the event text and hands the tags to the 0-LLM write path.
+
+Convention (either works):
+    FERN_TAGS: pref:concise topic:python goal:launch
+    <!--FERN pref:concise topic:python-->
+"""
+from __future__ import annotations
+import re
+from typing import Dict, List
+
+from .base import BaseAdapter
+from ..safety import sanitize_tags
+
+_LINE = re.compile(r"FERN_TAGS:\s*(.+)", re.IGNORECASE)
+_HTML = re.compile(r"<!--\s*FERN\s+(.+?)-->", re.IGNORECASE | re.DOTALL)
+
+
+class AgentByproductAdapter(BaseAdapter):
+    name = "agent"
+    cost_label = "~20-40 tokens/write — emitted inside a reply already happening (no separate call)"
+    cost_tokens = 30
+    reads_text = True
+    needs = "a host agent that appends a 'FERN_TAGS:' line"
+
+    def __init__(self, marker: str = "FERN_TAGS:"):
+        self.marker = marker
+
+    def extract(self, event: Dict) -> List[str]:
+        # explicit tags passed by the agent win outright
+        tags: List[str] = list(event.get("tags", []))
+        text = event.get("text") or ""
+        m = _LINE.search(text) or _HTML.search(text)
+        if m:
+            tags += [t for t in re.split(r"[\s,]+", m.group(1).strip()) if ":" in t]
+        return sanitize_tags(tags)

fernme/capture/base.py

@@ -0,0 +1,51 @@
+"""Capture adapters — the *perception* layer that sits above the 0-LLM engine.
+
+The FERNme write (`service.observe`) is pure graph arithmetic: 0 LLM tokens,
+always. What differs per deployment is only *how tags are produced* from
+experience. Each adapter is one way to turn an event into tags, and carries an
+honest `cost_label` / `cost_tokens` so an installer can tell the user exactly
+what it will cost — no hidden LLM calls.
+
+  signal   structured events (command/file/git/app/calendar) -> rules. 0 tokens.
+  local    text -> local keyword rules, or a small local model (Ollama). 0 API
+           tokens; uses your own CPU/GPU.
+  agent    the host agent (Claude Cowork, Codex, ...) emits a tiny tag line as a
+           byproduct of the reply it is already writing. ~20-40 output tokens,
+           no *separate* LLM call.
+
+Adapters only PROPOSE tags. They are sanitized and written through the normal
+no-LLM path, so the engine stays the single source of truth.
+"""
+from __future__ import annotations
+from typing import Dict, List
+
+# An "event" is a plain dict. Conventional keys:
+#   kind : str  -- "chat" | "command" | "file" | "git" | "app" | "calendar"
+#   text : str  -- free text (for chat / local tagger)
+#   ...  : adapter-specific fields (cmd, path, repo, msg, name, title, ...)
+
+
+class BaseAdapter:
+    """One way to turn an event into proposed tags.
+
+    Subclasses set the class attributes and implement `extract`. `cost_tokens`
+    is the rough per-write LLM-token cost this adapter *causes* (0 means it
+    spends no model tokens at all)."""
+
+    name: str = "base"
+    cost_label: str = ""
+    cost_tokens: int = 0          # rough billed tokens caused per write
+    reads_text: bool = False      # whether it consumes event["text"]
+    needs: str = "nothing"        # human note: what must be present to use it
+
+    def extract(self, event: Dict) -> List[str]:
+        raise NotImplementedError
+
+    # convenience so adapters are printable in the installer table
+    def info(self) -> Dict:
+        return {
+            "name": self.name,
+            "cost_label": self.cost_label,
+            "cost_tokens": self.cost_tokens,
+            "needs": self.needs,
+        }

fernme/capture/config.py

@@ -0,0 +1,81 @@
+"""Read/write `fern.toml` — which capture adapters are active and their options.
+
+Dependency-free: a tiny targeted TOML reader/writer for our small, known schema
+(so it works on any Python with no `tomli`/`tomllib` requirement). Shape:
+
+    [capture]
+    active = ["agent", "signal"]
+
+    [capture.local]
+    mode = "rules"          # rules | model
+    model = "hermes3"
+    endpoint = "http://localhost:11434"
+
+    [capture.agent]
+    marker = "FERN_TAGS:"
+"""
+from __future__ import annotations
+import os
+import re
+from typing import Dict, List
+
+DEFAULT_PATH = "fern.toml"
+VALID = ("signal", "local", "agent")
+
+
+def default_config(active: List[str] = None) -> Dict:
+    return {
+        "active": list(active) if active else ["agent", "signal"],
+        "local": {"mode": "rules", "model": "hermes3",
+                  "endpoint": "http://localhost:11434"},
+        "agent": {"marker": "FERN_TAGS:"},
+    }
+
+
+_ACTIVE = re.compile(r'^\s*active\s*=\s*\[(.*?)\]', re.MULTILINE)
+_SECTION = re.compile(r'^\s*\[capture\.(\w+)\]\s*$')
+_KV = re.compile(r'^\s*(\w+)\s*=\s*"(.*?)"\s*$')
+
+
+def load_config(path: str = DEFAULT_PATH) -> Dict:
+    """Parse fern.toml; missing file -> default config."""
+    cfg = default_config()
+    if not os.path.exists(path):
+        return cfg
+    with open(path, "r", encoding="utf-8") as f:
+        text = f.read()
+    m = _ACTIVE.search(text)
+    if m:
+        items = [s.strip().strip('"').strip("'") for s in m.group(1).split(",")]
+        cfg["active"] = [s for s in items if s in VALID]
+    section = None
+    for line in text.splitlines():
+        sm = _SECTION.match(line)
+        if sm:
+            section = sm.group(1)
+            cfg.setdefault(section, {})
+            continue
+        if section:
+            kv = _KV.match(line)
+            if kv:
+                cfg[section][kv.group(1)] = kv.group(2)
+    return cfg
+
+
+def write_config(cfg: Dict, path: str = DEFAULT_PATH) -> str:
+    active = ", ".join('"%s"' % a for a in cfg.get("active", []))
+    lines = ["# FERNme capture config — which perception adapters are active.",
+             "# The engine write is always 0-LLM; only tag *production* differs.",
+             "", "[capture]", "active = [%s]" % active, ""]
+    for sec in ("local", "agent"):
+        opts = cfg.get(sec)
+        if not opts:
+            continue
+        lines.append("[capture.%s]" % sec)
+        for k, v in opts.items():
+            lines.append('%s = "%s"' % (k, v))
+        lines.append("")
+    out = "\n".join(lines)
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(out)
+    return path

fernme/capture/install.py

@@ -0,0 +1,93 @@
+"""Installer / picker for FERNme capture methods.
+
+Prints a plain cost table so the user sees exactly what each method does and how
+many tokens it costs, then writes `fern.toml`. Runnable two ways:
+
+    python -m fernme.capture.install                 # interactive picker
+    python -m fernme.capture.install --methods agent,signal --out fern.toml
+    python -m fernme.capture.install --show          # just print the table
+"""
+from __future__ import annotations
+import argparse
+import sys
+from typing import List
+
+from .base import BaseAdapter
+from . import REGISTRY, VALID, default_config, write_config
+
+# stable display order + one-line "captures" note per method
+_ORDER = ["agent", "signal", "local"]
+_CAPTURES = {
+    "agent": "full chat meaning (host agent emits tags)",
+    "signal": "behavior only: commands, files, git, apps, calendar",
+    "local": "full chat meaning, on your own machine",
+}
+
+
+def _adapter(name: str) -> BaseAdapter:
+    return REGISTRY[name]()
+
+
+def cost_table() -> str:
+    rows = [("METHOD", "TOKEN COST", "CAPTURES", "NEEDS")]
+    for name in _ORDER:
+        a = _adapter(name)
+        cost = "0 (free)" if a.cost_tokens == 0 else "~%d/write" % a.cost_tokens
+        rows.append((name, cost, _CAPTURES[name], a.needs))
+    w = [max(len(r[i]) for r in rows) for i in range(4)]
+    line = lambda r: "  ".join(r[i].ljust(w[i]) for i in range(4))
+    sep = "  ".join("-" * w[i] for i in range(4))
+    out = [line(rows[0]), sep] + [line(r) for r in rows[1:]]
+    note = ("\nNotes: 'agent' also costs ~25-50 tokens per *read* (the memory card "
+            "injected into the\nagent's context). 'signal' and 'local' write only "
+            "— no read-side token cost. Zero-token\nmethods trade recall for cost: "
+            "they catch less nuance than a model would.")
+    return "\n".join(out) + "\n" + note
+
+
+def _interactive() -> List[str]:
+    print("\nFERNme — choose how memory gets written.\n")
+    print(cost_table())
+    print("\nYou can pick more than one (they stack). Example: agent,signal\n")
+    raw = input("Methods [agent,signal]: ").strip() or "agent,signal"
+    chosen = [m.strip() for m in raw.split(",") if m.strip() in VALID]
+    return chosen or ["agent", "signal"]
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(description="Install FERNme capture methods.")
+    p.add_argument("--methods", help="comma list: %s" % ",".join(_ORDER))
+    p.add_argument("--out", default="fern.toml", help="config path to write")
+    p.add_argument("--show", action="store_true", help="print the cost table and exit")
+    args = p.parse_args(argv)
+
+    if args.show:
+        print(cost_table())
+        return 0
+
+    if args.methods:
+        chosen = [m.strip() for m in args.methods.split(",") if m.strip() in VALID]
+        bad = [m.strip() for m in args.methods.split(",") if m.strip() not in VALID]
+        if bad:
+            print("ignored unknown methods: %s (valid: %s)" % (bad, ", ".join(VALID)),
+                  file=sys.stderr)
+        if not chosen:
+            print("no valid methods given", file=sys.stderr)
+            return 2
+    else:
+        chosen = _interactive()
+
+    cfg = default_config(active=chosen)
+    path = write_config(cfg, args.out)
+    print("\nWrote %s with active methods: %s" % (path, ", ".join(chosen)))
+    total = sum(_adapter(n).cost_tokens for n in chosen)
+    print("Estimated write cost: %s tokens%s" % (
+        total, " (free)" if total == 0 else " per write"))
+    if "local" in chosen:
+        print("local: starts in rules mode (0 tokens). Install Ollama + a model and "
+              "set mode=\"model\" in fern.toml to upgrade.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())