Ollama Intern

English | 日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

The local intern for Claude Code. 44 job-shaped tools, evidence-first briefs, durable artifacts.

An MCP server that gives Claude Code a local intern with rules, tiers, a desk, and a filing cabinet. Claude picks the tool; the tool picks the tier (Instant / Workhorse / Deep / Embed); the tier writes a file you can open next week.

Also drives Hermes Agent on hermes3:8b — validated end-to-end 2026-04-19. The default ladder is hermes3:8b; qwen3:* is the alternate rail. See Use with Hermes below.

Hardware requirements: ~6 GB VRAM for hermes3:8b, or ~16 GB RAM for CPU inference. See handbook/getting-started for the full breakdown.

Not using Claude? The examples/ directory has a minimal Node.js and Python MCP client you can spawn over stdio. See also handbook/with-hermes.

Local-first — zero network egress until you opt in. No telemetry. No "autonomous" anything. Every call shows its work.

No GPU big enough? Ollama Cloud runs all 44 tools on 600B-class models. Most people can't host a frontier model on their own card — that's the real ceiling on local AI, and it's the one this lifts. Same /api/* surface, same job-shaped tools, same envelopes; embeddings stay local; any cloud failure falls back to your local profile automatically. Escalate one call (backend: "cloud") or route every generative call (OLLAMA_CLOUD_PRIMARY=1) — and every envelope tells you which backend actually served it. Off until you set a key.

---

New in v2.10.0

The cloud-honesty release. v2.9.0 shipped per-call cloud escalation and this README advertised "escalate one high-stakes review to a 600B model" — but the backend input existed on exactly one of the 44 tools, and it was ollama_chat, which its own description calls a last resort. Every review-shaped job was pinned to a local 8B. Local-first is unchanged: no key still means zero egress and no startup probe, embeddings never leave the box, and every new knob defaults to today's behavior.

• Per-call escalation now reaches 15 tools, not 1. backend: "cloud" is an optional input on research, summarize_deep, code_review, code_citation, corpus_answer, hypothesis_drill, multi_file_refactor_propose, refactor_plan, all three briefs, all three packs, and chat. Omit it and behavior is byte-identical to v2.9.x. Packs escalate their synthesis step only — evidence assembly, triage and artifact writes stay local — and refuse an unservable escalation before doing any local work.
• INTERN_CLOUD_STANDBY_TIERS — declare the policy once. Name which tiers (instant|workhorse|deep) escalate under standby without a per-call directive. Empty by default. A per-call backend still outranks it in both directions. embed is refused at config load and at the routing layer: embeddings always stay local.
• doctor --cloud-check — prove the key actually works. The old probe hit /api/tags, which returns 200 for an invalid key, so auth could only ever read "unverified". This runs one 8-token generate and returns ok / failed / unverified / unreachable — four states kept distinct on purpose, because a 404 on a model id is not a key problem and shouldn't send you hunting one. It also reports each configured cloud id as present or NOT IN CATALOG with a nearest-live-id suggestion, so a retired id is found before you pay for a degraded call.
• Fixed: init was broken on every npm install. hermes.config.example.yaml never made it into the published tarball, so the binary reported its own "packaging bug" error to anyone who installed from npm. It ships now, and CI installs and runs the packed tarball so it cannot regress.
• Retrieval scores are finally comparable. CorpusHit.score carried four incomparable scales under one field — the default hybrid mode topped out at 0.0328 while corpus_min_evidence_score was documented "0–1", so a natural floor of 0.1 silently dropped every corpus chunk. Fused scores are rescaled onto 0–1 and each hit carries score_scale.

Full detail in CHANGELOG.md.

New in v2.9.0

The cloud feature pass — a cross-family verification lane, on-demand cloud escalation, and the economics to see it. Local-first is unchanged: with no key set, behavior is byte-identical to v2.8.0 (zero egress, no startup cloud probe).

• ollama_verify_claims — cross-family verification. ollama_code_review generates findings; this adjudicates them. It runs a disjoint-family Ollama Cloud flagship panel (deepseek / kimi / glm by default) over your claims + evidence and returns per-claim CONFIRMED / REFUTED / NEEDS_REVIEW. Aggregation is lone-dissent-never-decides (≥2 to refute, ≥2 to confirm), every juror is served-model-verified (a local fallback or substituted model is excluded, never counted), and claim inputs are structurally reasoning-stripped. The honest ceiling is documented: a CONFIRMED is supporting evidence, not proof — reliable at flagging gross errors, weaker on a frontier model's subtle ones.
• Per-call cloud escalation + standby mode. Set OLLAMA_API_KEY alone (without OLLAMA_CLOUD_PRIMARY) and you're in standby: local-primary, zero egress, no startup probe — until a single call opts in with backend:'cloud'. Escalate one high-stakes review to a 600B model without flipping every call to cloud. The first escalation discloses egress loudly at the point it happens; a per-call model override now rides the cloud attempt verbatim.
• ollama_log_stats — the measured economics the tagline promises. A no-LLM rollup of your NDJSON receipts: cloud/local split, cloud→local fallback rate, tokens per tool, p50/p95 latency, bounded by a since window.
• Doctor for CI + machine-readable tools. doctor --json --fail-unhealthy gives pipelines a real gate (with a cloud-aware healthy flag), and every tool now carries MCP readOnlyHint/destructiveHint/title annotations so clients get correct permission UX. Plus init --claude scaffolds a paste-ready .mcp.json.

Full detail in CHANGELOG.md.

New in v2.8.0

Reliability, durability, and security hardening — 25 fixes, every one test-first and cross-family-verified. Local-first behavior is unchanged and no tool contract was removed; existing callers keep working. The load-bearing wins:

• No more silent corpus data-loss. A transient read error during ollama_corpus_refresh (a Windows file lock, an antivirus hold, an editor's save window) used to classify the file "missing" and permanently delete its indexed content. Now only a genuinely-absent file is dropped; a transient error keeps the path, flags it for retry, and preserves its chunks.
• Concurrency that honors its budgets. A tier timeout can now cancel a call still queued for a permit (it used to hang far past budget while receipts claimed otherwise), and ollama_chat finally routes through the timeout/tier seam — so one wedged local generation can't stall every tool, and it actually reaches cloud in cloud-primary mode.
• Cloud that degrades instead of dying. A retired cloud-model id now falls back to local with a clear cloud_model_missing reason and a cloud-specific hint instead of a total outage; the circuit breaker can't wedge permanently; a persistently-missing model stops paying a cloud round-trip on every call.
• Security surface that matches its docs. ollama_batch_proof_check now really enforces cwd containment (with a new operator env cap INTERN_BATCH_PROOF_ALLOWED_ROOTS a caller can't widen), the prompt-injection sanitizers gained coverage + an honestly-disclosed ceiling, and the protected-path guard is case-insensitive on macOS too.
• Honest artifacts & receipts. Pack writes are atomic and never silently clobber; degraded batch envelopes report the tier actually used; the interrupted-write detector catches torn writes on any mutation; chunk IDs no longer collide across identical-content files. Dependency audit is fully clear (0 vulnerabilities).

Full detail in CHANGELOG.md.

New in v2.7.0

Optional Ollama Cloud routing — cloud-primary, local-fallback. Opt in with a key + a flag and the generative tiers route to a 600B-class cloud model; embeddings stay local; a circuit breaker falls back to your local profile on any cloud failure. Off by default — zero egress unless you set both OLLAMA_API_KEY and OLLAMA_CLOUD_PRIMARY=1. Additive minor — pre-v2.7.0 callers (and anyone not opting in) see byte-identical behavior. See Ollama Cloud.

• Cloud-primary with a safety net. A RoutingOllamaClient tries cloud first and falls back to the local profile on timeout / 5xx / 429 / network. Bad keys (401/403) surface loudly via a sticky breaker instead of degrading silently forever; a retired/typo'd cloud model id (404) surfaces too.
• Never a silent downgrade. Every envelope gains backend (cloud|local), degraded, and degrade_reason so you always know when you got the local model instead of the big one. A backend_fallback NDJSON event makes the cloud→local fallback rate visible in ollama_log_tail.
• ollama_doctor reports cloud auth + reachability as a distinct block; ollama-intern-mcp doctor shows a Cloud (primary) section.
• Default cloud model was minimax-m3:cloud at v2.7.0 release (since repinned to mistral-large-3:675b-cloud — a thinking default returned empty replies on capped-num_predict tools; see the env table); override per-tier with INTERN_CLOUD_MODEL / INTERN_CLOUD_DEEP_MODEL.

New in v2.6.0

Per-call tier-budget override on ollama_extract. Additive minor — pre-v2.6.0 callers unchanged. Detailed entry in CHANGELOG.md.

• tier_budget_ms_override?: number schema field on ollama_extract (optional, bounded [1, 600000] ms). When present, applies the override to every tier visited by the runner so the inner runWithTimeoutAndFallback machinery at src/guardrails/timeouts.ts:61 honors the operator-supplied budget instead of the profile default. The cascade (workhorse → instant on timeout) still fires; the override governs each cascade hop uniformly.
• Why this exists. The research-os R-018 wrapper (v0.12.1) wrapped MCP callTool with Promise.race and found the wrapper's budget did not reach the inner tier — DEV_RTX5080_TIMEOUTS.instant = 15_000 continued to fire TIER_TIMEOUT at 15000ms regardless of a 180000ms wrapper budget. v2.6.0 supplies the MCP-side authoritative budget so the operator's --planner-timeout-ms flag (research-os) finally controls inner-tier timeouts as designed.
• Default behavior preserved. Field omitted = profile defaults govern byte-identically. Pre-v2.6.0 callers see zero change.
• R-010 fallback-cause regex preserved. Server-side TIER_TIMEOUT error message still matches /elapsed=(\d+)ms/ + /budget=(\d+)ms/ so AI-advisor visibility downstream works on override and default paths alike.
• Consumed by research-os v0.13.0 (cumulative R-019 client wire-up + R-020 + R-021) in a coordinated multi-repo release.

Historical — v2.4.0 deliverables

See CHANGELOG.md and docs/release-notes/v2.4.0.md for the full v2.4.0 entry (per-tier num_ctx control on the profile system).

New in v2.4.0

Per-tier num_ctx (context window) control on the profile system. Additive minor — v2.3.0 callers unchanged. Detailed entries in CHANGELOG.md and docs/release-notes/v2.4.0.md.

• TierConfig.num_ctx map (new) — optional { instant?, workhorse?, deep?, embed? } on the profile. When set for a tier, the MCP server places options.num_ctx = <value> on every Ollama generate/chat request routed to that tier (initial + fallback). When unset, the request omits num_ctx entirely so Ollama uses its model-loaded default — v2.3.0 behavior preserved exactly.
• New envelope field num_ctx_used?: number — present only when the MCP server actually sent num_ctx. Absent when the request let Ollama choose. Do not infer a default — the MCP server does not query Ollama for the effective value.
• Profile defaults: dev-rtx5080 / dev-rtx5080-qwen3 ship with instant: 4096, workhorse: 8192, deep/embed UNSET. Sized to keep hermes3:8b resident in the RTX 5080's 16GB VRAM budget for fast tools. m5-max leaves every tier UNSET — 128GB unified memory has no spill problem.
• Closes the v0.8.0 Phase 1 diagnostic — hermes3:8b at the default 32K context on RTX 5080 spilled to CPU and started timing out workhorse ollama_extract calls. v2.4.0 prevents that at the profile layer.

Per-tier num_ctx control (new in v2.4.0)

Profile (excerpt from src/profiles.ts):

"dev-rtx5080": {
  tiers: {
    instant: "hermes3:8b",
    workhorse: "hermes3:8b",
    deep: "hermes3:8b",
    embed: "nomic-embed-text",
    num_ctx: {
      instant: 4096,    // fast classify/summarize
      workhorse: 8192,  // schema-bound extract / batch
      // deep: UNSET — long-context briefs keep current behavior
      // embed: UNSET — no context-window pressure on embed
    },
  },
  // ... timeouts, prewarm
}

Envelope on a workhorse-tier call (e.g. ollama_extract):

{
  "result": { /* extracted data */ },
  "tier_used": "workhorse",
  "model": "hermes3:8b",
  "num_ctx_used": 8192,        // present because the profile set workhorse=8192
  // ... rest of envelope unchanged
}

On m5-max (or any profile that leaves a tier unset), num_ctx_used is absent from the envelope and the wire request to Ollama does not include the num_ctx field — Ollama uses its model-loaded default.

Operators tune by selecting / editing the profile; there is no per-call num_ctx input on tool schemas. If a future call surfaces the need, the pattern follows v2.3.0's model override.

Historical — v2.3.0 deliverables

See CHANGELOG.md and docs/release-notes/v2.3.0.md for the full v2.3.0 entry (per-call model override).

New in v2.3.0

Per-call model override across LLM-backed atom tools. Additive minor — v2.2.0 callers unchanged. Detailed entries in CHANGELOG.md and docs/release-notes/v2.3.0.md.

• Optional model: string input on 8 atom tools — ollama_extract, ollama_classify, ollama_summarize_fast, ollama_summarize_deep, ollama_research, ollama_corpus_answer, ollama_chat, ollama_code_citation. The first attempt on the tool's tier runs against the caller-specified model; on timeout, the existing TIER_FALLBACK cascade resolves the cheaper tier's own model (NOT the caller's override). Composite/brief/pack tools deliberately do NOT accept model — atoms get per-call control, composites use tier defaults.
• New envelope field model_requested?: string — present only when the override was supplied. Calibration-aware callers compare model_requested vs model to detect fallback substitution: if (env.model_requested && env.model !== env.model_requested) { /* substitution */ }. Empty / whitespace-only inputs throw ZodError at schema parse, not silent fallthrough.
• Bug fix — src/version.ts drift. The runtime VERSION constant is now read from package.json at module load; v2.1.0 and v2.2.0 had shipped reporting the stale "2.0.0" identity string. New tests/version.test.ts locks VERSION === pkg.version.

Per-call model override (new in v2.3.0)

{
  "tool": "ollama_classify",
  "arguments": {
    "text": "patch null pointer in auth",
    "labels": ["feat", "fix", "chore"],
    "frame": "what is the change kind?",
    "model": "hermes3:8b"
  }
}

Envelope:

{
  "result": { "label": "fix", "confidence": 0.9, "off_topic": false, ... },
  "tier_used": "instant",
  "model": "hermes3:8b",
  "model_requested": "hermes3:8b",       // present because override was supplied
  // ... rest of envelope unchanged
}

If the workhorse/deep tier had timed out and the call had cascaded to the instant tier, env.model would be the instant tier's resolved model and env.fallback_from would be "workhorse" — env.model_requested would still be "hermes3:8b", and env.model !== env.model_requested is the substitution signal. The override is deliberately NOT carried into the cheaper tier; the chosen model may not fit that tier's role at all.

Historical — v2.2.0 deliverables

See CHANGELOG.md and docs/release-notes/v2.2.0.md for the full v2.2.0 entry (frame-bound topicality + structured abstention).

New in v2.2.0

Local evidence-worker role contract: frame-bound topicality and structured abstention. Additive minor — v2.1.0 callers unchanged. Detailed entries in CHANGELOG.md and docs/release-notes/v2.2.0.md.

• Frame-bound extraction on ollama_extract, ollama_classify, ollama_summarize_fast, ollama_summarize_deep — optional frame: string input + structured frame_alignment / on_topic / frame_addressed outputs. Off-topic sources are flagged instead of paraphrased into the schema.
• Structured abstention on ollama_research — weak / abstained / sources_address_question fields. Empty citations[] with non-empty answer is no longer silent success.
• Topicality threshold on ollama_corpus_answer — optional min_top_score. Below the floor, the tool short-circuits with abstained: true and skips synthesis. Per-citation score now visible on each citation.
• Retrieval score preservation through brief evidence — corpusHitsToEvidence carries score (and corpus_min_evidence_score knob filters at assembly time on incident_brief / repo_brief / change_brief).
• Citation line-range bounds — guardrails/citations.ts rejects out-of-bounds ranges on ollama_research, matching the existing posture on ollama_code_citation.
• Operator-contract docs corrected — README chunk_id/chunk_index fix, "validated server-side" rewritten, Evidence Laws section qualified, marketing slogan annotated.

Seed regression — the verification

The slice's contract is verified against the literal research-os fresh-pack failure: arxiv 2112.10422 (Cosmological Standard Timers) under the section-01 frame "What does evidence custody mean in local-first vs cloud LLM deep-research workflows?" — 9 / 9 mocked-LLM contract tests confirm the off-topic source is now contained (frame_alignment.on_topic = false on extract; off_topic: true on classify; frame_addressed: false on summarize_deep; abstained: true on corpus_answer with min_top_score set).

Historical — v2.1.0 deliverables

See CHANGELOG.md for the full v2.1.0 entry (feature pass: 13 new tools + 4 enhancements + freeze lift).

---

Architecture at a glance

flowchart LR
  Claude["Claude Code<br/>(MCP client)"]
  MCP["ollama-intern-mcp<br/>server (stdio)"]
  Ollama["Ollama daemon<br/>(127.0.0.1:11434)"]
  Models[("Hermes 3 / Qwen 3<br/>nomic-embed-text")]
  Corpus[("~/.ollama-intern/<br/>corpora/")]
  Artifacts[("~/.ollama-intern/<br/>artifacts/")]
  NDJSON[("~/.ollama-intern/<br/>log.ndjson")]
  Guards{{"Guardrails<br/>citations · banned phrases<br/>protected paths · confidence"}}

  Claude -- "JSON-RPC over stdio" --> MCP
  MCP --> Guards
  MCP -- "/api/generate · /api/chat<br/>/api/embed · /api/ps · /api/tags" --> Ollama
  Ollama --> Models
  MCP --- Corpus
  MCP --- Artifacts
  MCP --> NDJSON

Every Claude tool call enters the MCP server over stdio JSON-RPC. The server validates the call against the tool's zod schema, runs the configured guardrails (citation validation, banned-phrase strip, protected-path enforcement, confidence thresholds), then routes to either a deterministic renderer (artifact tier) or an Ollama HTTP call (every other tier). The Ollama daemon never sees user-supplied paths — only the model tier and the prepared prompt. Every call appends one structured event to the NDJSON log at ~/.ollama-intern/log.ndjson, where ollama_log_tail and your shell can read it.

---

Lead example — one call, one artifact

// Claude → ollama-intern-mcp
{
  "tool": "ollama_incident_pack",
  "arguments": {
    "title": "sprite pipeline 5 AM paging regression",
    "logs": "[2026-04-16 05:07] worker-3 OOM killed\n[2026-04-16 05:07] ollama /api/ps reports evicted=true size=8.1GB\n...",
    "source_paths": ["F:/AI/sprite-foundry/src/worker.ts", "memory/sprite-foundry-visual-mastery.md"]
  }
}

Returns an envelope pointing at a file on disk:

{
  "result": {
    "pack": "incident",
    "slug": "2026-04-16-sprite-pipeline-5-am-paging-regression",
    "artifact_md":   "~/.ollama-intern/artifacts/incident/2026-04-16-sprite-pipeline-5-am-paging-regression.md",
    "artifact_json": "~/.ollama-intern/artifacts/incident/2026-04-16-sprite-pipeline-5-am-paging-regression.json",
    "weak": false,
    "evidence_count": 6,
    "next_checks": ["residency.evicted across last 24h", "OLLAMA_MAX_LOADED_MODELS vs loaded size"]
  },
  "tier_used": "deep",
  "model": "hermes3:8b",
  "hardware_profile": "dev-rtx5080",
  "tokens_in": 4180, "tokens_out": 612,
  "elapsed_ms": 8410,
  "residency": { "in_vram": true, "evicted": false }
}

→ weak: false means ≥2 evidence items were assembled; it does NOT mean the hypotheses are vetted. See Evidence laws below.

That markdown file is the intern's desk output — headings, evidence block with cited ids, investigative next_checks, weak: true banner if evidence is thin. It's deterministic: the renderer is code, not a prompt. (The renderer is deterministic; the content of hypotheses and surfaces is generative — read them as draft, not verified.) Open it tomorrow, diff it next week, export it into a handbook with ollama_artifact_export_to_path.

Every competitor in this category leads with "save tokens." We lead with here is the file the intern wrote.

Second example — build a corpus, then ask it

// 1. Build a persistent, searchable corpus over your project.
{ "tool": "ollama_corpus_index",
  "arguments": { "name": "sprite-foundry",
                 "paths": ["F:/AI/sprite-foundry/src"],
                 "embed_model": "nomic-embed-text" } }
// → { chunks_written: 1204, paths_indexed: 312, failed_paths: [] }

// 2. Ask an evidence-bound question against it.
{ "tool": "ollama_corpus_answer",
  "arguments": { "name": "sprite-foundry",
                 "query": "how does the worker handle OOM eviction?",
                 "top_k": 8 } }
// → { answer: "...", citations: [{chunk_index, path}...], weak: false }

The server validates citation identity and that each chunk_index is in range of the retrieved hits. It does NOT prove that every generated claim is semantically supported by the cited chunk content — that's the model's responsibility, and weak retrieval can still produce citation-shaped answers. Full walkthrough in handbook/corpora.

---

Frame-bound extraction (new in v2.2.0)

ollama_extract, ollama_classify, ollama_summarize_fast, and ollama_summarize_deep accept an optional frame: string input. The frame names the question the source is being asked to answer; the model is instructed to abstain rather than emit true-but-off-topic content when the source doesn't address the frame.

{
  "tool": "ollama_extract",
  "arguments": {
    "text": "<long source document>",
    "schema": { /* your fields */ },
    "frame": "section purpose here — e.g. 'OOM eviction behavior in the sprite worker'"
  }
}
// → result includes frame_alignment: { on_topic: boolean, reason: string, unaddressed_aspects: string[] }

If frame is omitted, behavior is unchanged from v2.1.0. When supplied, frame_alignment.on_topic = false signals that extracted fields may be true-of-the-source but not relevant to the frame — treat that as the same shape as a weak: true brief: useful, but spot-check before promoting into downstream evidence.

---

Abstention contract (new in v2.2.0)

ollama_research returns structured abstention fields: weak: boolean, abstained: boolean, sources_address_question: boolean | null. An empty citations[] with a non-empty answer is no longer silent — abstained: true says the model declined to synthesize because the caller-supplied paths did not address the question. Treat abstention as a success, not a failure: it is the tool refusing to launder weak retrieval into authoritative output.

ollama_corpus_answer accepts an optional min_top_score: number topicality threshold (0.0–1.0). When the top retrieval score for a query falls below min_top_score, the tool short-circuits with abstained: true and skips synthesis — preventing the "5 off-topic chunks at score 0.21 still drive a full answer" failure mode that the v2.1.0 weak: true rule did not catch (weak: true only fired on hits.length < 2). Pair this with the per-citation score field newly surfaced on each citation to audit retrieval quality directly from the envelope.

---

What's in here — four tiers, 44 tools

Job-shaped means each tool names a job you'd hand to an intern — classify this, extract that, triage these logs, draft this release note, pack this incident. The tool's input is the job spec; the output is the deliverable. No generic run_model / chat_with_llm primitive at the top.

Tier	Count	What lives here
Atoms	31	Job-shaped primitives. Original 15: classify, extract, triage_logs, summarize_fast / deep, draft, research, corpus_search / answer / index / refresh / list, embed_search, embed, chat. +13 added in v2.1.0: doctor, log_tail, batch_proof_check (ops); code_map, code_citation, multi_file_refactor_propose, refactor_plan (refactor); artifact_prune, hypothesis_drill (artifact/brief); corpus_health, corpus_amend, corpus_amend_history, corpus_rerank (corpus). +1 review atom: code_review (structured PR-review findings, workhorse; review-only). +2 in v2.9: verify_claims (cross-family cloud flagship panel adjudicates claims; cloud-required) and log_stats (aggregate the NDJSON receipts into measured economics — cloud/local split, fallback rate, p50/p95 per tool; no model call). Batch-capable atoms (classify, extract, triage_logs) accept items: [{id, text}].
Briefs	3	Evidence-backed structured operator briefs. incident_brief, repo_brief, change_brief. Every claim cites an evidence id; unknowns stripped server-side. Weak evidence surfaces weak: true rather than fake narrative.
Packs	3	Fixed-pipeline compound jobs that write durable markdown + JSON to ~/.ollama-intern/artifacts/. incident_pack, repo_pack, change_pack. Deterministic renderers — no model calls on the artifact shape.
Artifacts	7	Continuity surface over pack outputs. artifact_list / read / diff / export_to_path, plus three deterministic snippets: incident_note, onboarding_section, release_note.

Total: 31 atoms + 3 briefs + 3 packs + 7 artifact tools = 44.

Freeze lines:

• Atoms: freeze lifted at v2.1.0 (31 today; +13 added in the v2.1.0 feature pass, +1 code_review later, +2 in v2.9: verify_claims, log_stats). New atoms still require an audit-justified gap, tests, handbook page, and CHANGELOG entry — no casual additions.
• Packs frozen at 3. No new pack types.
• Artifact tier frozen at 7.

The full tool reference lives in the handbook.

---

Install

Requires Ollama running locally and the tier models pulled (see Model pulls below).

Claude Code (recommended)

Most users install this by adding it to their Claude Code MCP server config — no global install required. Claude Code runs the server on demand via npx:

{
  "mcpServers": {
    "ollama-intern": {
      "command": "npx",
      "args": ["-y", "ollama-intern-mcp"],
      "env": {
        "OLLAMA_HOST": "http://127.0.0.1:11434",
        "INTERN_PROFILE": "dev-rtx5080"
      }
    }
  }
}

Claude Desktop

Same block, written to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Global install (advanced)

Only needed if you want the binary on your PATH for ad-hoc use outside Claude Code:

npm install -g ollama-intern-mcp

Use with Hermes

This MCP was validated end-to-end with Hermes Agent against hermes3:8b on Ollama (2026-04-19). Hermes is an external agent that calls into this MCP's frozen primitive surface — it does the planning, we do the work.

Reference config (hermes.config.example.yaml in this repo):

model:
  provider: custom
  base_url: http://localhost:11434/v1
  default: hermes3:8b
  context_length: 65536    # Hermes requires 64K floor under model.*

providers:
  local-ollama:
    name: local-ollama
    base_url: http://localhost:11434/v1
    api_mode: openai_chat
    api_key: ollama
    model: hermes3:8b

mcp_servers:
  ollama-intern:
    command: npx
    args: ["-y", "ollama-intern-mcp"]
    env:
      OLLAMA_HOST: http://localhost:11434
      INTERN_PROFILE: dev-rtx5080
      # hermes3:8b is the default ladder in v2.0.0, so tier overrides are
      # only needed if you're pinning a different local model.

Prompt shape matters. Imperative tool-invocation prompts ("Call X with args …") are the integration test — they give an 8B local model enough scaffolding to emit clean tool_calls. List-form multi-task prompts ("do A, then B, then C") are capability benchmarks for larger models; don't interpret a list-form failure on 8B as "the wiring is broken." See handbook/with-hermes for the full integration walkthrough + known transport caveats (Ollama /v1 streaming + openai-SDK non-streaming shim).

Model pulls

Default dev profile (RTX 5080 16GB and similar):

ollama pull hermes3:8b
ollama pull nomic-embed-text
export OLLAMA_MAX_LOADED_MODELS=2

Qwen 3 alternate rail (same hardware, for Qwen tooling):

ollama pull qwen3:8b
ollama pull qwen3:14b
ollama pull nomic-embed-text
export INTERN_PROFILE=dev-rtx5080-qwen3

M5 Max profile (128GB unified):

ollama pull qwen3:14b
ollama pull qwen3:32b
ollama pull nomic-embed-text
export INTERN_PROFILE=m5-max

Per-tier env vars (INTERN_TIER_INSTANT, INTERN_TIER_WORKHORSE, INTERN_TIER_DEEP, INTERN_EMBED_MODEL) still override profile picks for one-offs.

Residency. On the dev profiles the server prewarms the Instant model at startup with a bounded keep_alive (10 minutes) so the first call is never cold; after any real call, Ollama's own idle eviction (default 5 minutes after the last request) governs. Set INTERN_PREWARM=off to skip the startup warm entirely — the right mode when the GPU is shared with training or rendering: models load on first use and idle out on their own. Raising OLLAMA_KEEP_ALIVE is for boxes dedicated to Ollama; -1 pins every touched model in VRAM until the server restarts.

---

Uniform envelope

Every tool returns the same shape:

{
  result: <tool-specific>,
  tier_used: "instant" | "workhorse" | "deep" | "embed",
  model: string,
  hardware_profile: string,     // "dev-rtx5080" | "dev-rtx5080-qwen3" | "m5-max"
  tokens_in: number,
  tokens_out: number,
  elapsed_ms: number,
  residency: {
    in_vram: boolean,
    size_bytes: number,
    size_vram_bytes: number,
    evicted: boolean
  } | null
}

residency comes from Ollama's /api/ps. When evicted: true or size_vram < size, the model paged to disk and inference dropped 5–10× — surface this to the user so they know to restart Ollama or trim loaded-model count.

In Ollama Cloud mode the envelope also carries backend ("cloud" | "local") and, on a cloud→local fallback, degraded: true + degrade_reason. These fields are absent in the default local-only path, so existing consumers are unaffected. residency is null for cloud-served calls (the stateless cloud has no local-VRAM residency).

Every call is logged as one NDJSON line to ~/.ollama-intern/log.ndjson. Filter by hardware_profile to keep dev numbers out of publishable benchmarks.

---

Hardware profiles

Profile	Instant	Workhorse	Deep	Embed
dev-rtx5080 (default)	hermes3 8B	hermes3 8B	hermes3 8B	nomic-embed-text
dev-rtx5080-qwen3	qwen3 8B	qwen3 8B	qwen3 14B	nomic-embed-text
m5-max	qwen3 14B	qwen3 14B	qwen3 32B	nomic-embed-text

Default dev collapses all three work tiers onto hermes3:8b — the validated Hermes Agent integration path. Same model top to bottom means there is one thing to pull, one residency cost, one set of behavior to understand. Users who prefer Qwen 3 (with its THINK_BY_SHAPE plumbing) opt into dev-rtx5080-qwen3. m5-max is the Qwen 3 ladder sized for unified memory.

---

Ollama Cloud

The hardware ceiling, lifted. A local 8B is what most machines can actually hold, and it is the bottleneck nearly everyone hits — not budget, not interest, just VRAM. Ollama Cloud serves 600B-class models behind the same /api/* surface, so the heavy tools run on a frontier model and your VRAM goes back to whatever else needs it. Local stays the always-on fallback, so you gain a ceiling without losing the floor.

Nothing about the tool surface changes: the same 44 job-shaped tools, the same envelope, the same guardrails. Embeddings never go to cloud (Ollama Cloud serves no embedding models), so corpora stay entirely local either way.

Opt-in and off by default. With no key set, the package stays local-first with zero egress — anyone who doesn't opt in is unaffected. There are two ways to opt in:

• Cloud-primary (below): set both OLLAMA_CLOUD_PRIMARY=1 and OLLAMA_API_KEY — the generative tiers route to cloud with local fallback.
• Cloud standby (v2.9): set only OLLAMA_API_KEY — everything stays local (still zero egress, not even a startup probe) until a single call explicitly asks to escalate with backend: "cloud". See Cloud standby & per-call escalation below.

{
  "mcpServers": {
    "ollama-intern": {
      "command": "npx",
      "args": ["-y", "ollama-intern-mcp"],
      "env": {
        "OLLAMA_CLOUD_PRIMARY": "1",
        "OLLAMA_API_KEY": "sk-...your-key...",
        "INTERN_PROFILE": "dev-rtx5080"
      }
    }
  }
}

The key is a runtime env var, not a CI secret. A GitHub Actions secret is only visible inside CI runs — it never reaches the running server. Create a key at ollama.com/settings/keys and put it in your MCP client's env block (or your shell environment).

How routing works. When cloud is on, the generative tiers (instant / workhorse / deep) go to the cloud model; embeddings always stay local (Ollama Cloud serves no embedding models, so the corpus/embed tools are unaffected). A circuit breaker tries cloud first and falls back to your local profile on timeout / 5xx / 429 / network errors. A bad key (401/403) trips a sticky breaker that surfaces loudly rather than degrading silently. The local profile (INTERN_PROFILE) is the fallback ladder, so keep its models pulled.

You're never silently downgraded. Every envelope reports which backend served the call:

{ ...envelope, backend: "cloud" | "local", degraded?: true, degrade_reason?: "cloud_timeout" | "cloud_5xx" | "cloud_rate_limited" | "cloud_unreachable" | "cloud_auth_failed" | "circuit_open" }

A backend_fallback line lands in ~/.ollama-intern/log.ndjson on every cloud→local fallback (ollama_log_tail --filter_kind backend_fallback), and ollama-intern-mcp doctor shows a Cloud (primary | standby) block with the mode, reachability, and auth status.

Cloud standby & per-call escalation

Setting OLLAMA_API_KEY without OLLAMA_CLOUD_PRIMARY arms standby: routing stays local-primary and nothing leaves the machine — until a call carries backend: "cloud" (exposed on ollama_chat, used internally by ollama_verify_claims). That one call escalates to the cloud model, with the same breaker + local-fallback machinery and the same envelope provenance; every other call stays local. The first escalated call prints a loud stderr disclosure naming the host and writes a cloud_egress line to the NDJSON log — egress is disclosed at the point it happens, not just here in the docs.

The rules, mechanically enforced:

• No key → backend: "cloud" fails with CLOUD_NOT_CONFIGURED. It is never silently served by the local model while claiming it escalated.
• Standby + no directive → local, zero egress (startup does not probe the cloud host either).
• Under cloud-primary, backend: "local" pins one call local — the inverse escape hatch.
• A per-call model override now rides the cloud path verbatim (it used to be clobbered by the tier→cloud-model map), so receipt-backed orchestrators can name the exact cloud model per call.

The flagship consumer is ollama_verify_claims: adjudicate claims/findings with a 3-model cross-family cloud panel (default deepseek-v4-pro:cloud / kimi-k2.7-code:cloud / glm-5.2:cloud) — lone-dissent-never-decides aggregation, served-model checks on every juror, and an honest weak flag when the panel thins. A CONFIRMED from the panel on frontier-model-authored claims is supporting evidence, not proof — the panel reliably catches gross errors and is weaker on subtle ones. See the handbook page.

Latency vs quality. Big cloud models run far slower per token than a local 8B (seconds, not milliseconds) — a quality upgrade, not a speed one. Cloud tiers use a generous timeout ladder (instant 30s / workhorse 120s / deep 300s by default).

Cloud env vars

Var	Default	Purpose
OLLAMA_CLOUD_PRIMARY	(unset)	The cloud-primary switch. 1/true/yes/on routes the generative tiers to cloud. Unset with a key = standby (local-primary, per-call escalation only). Unset without a key = local-only, zero egress.
OLLAMA_API_KEY	(unset)	Bearer key for Ollama Cloud. Setting it alone arms standby; required when OLLAMA_CLOUD_PRIMARY is enabled (fail-fast at startup if missing).
OLLAMA_CLOUD_HOST	https://ollama.com	Cloud base host.
INTERN_CLOUD_MODEL	mistral-large-3:675b-cloud	Cloud model for instant + workhorse + deep. Keep the default non-thinking — a thinking model here burns short-output budgets on CoT (put big reasoners on the deep override below).
INTERN_CLOUD_DEEP_MODEL	(= INTERN_CLOUD_MODEL)	Optional deep-tier-only override, e.g. deepseek-v3.1:671b.
INTERN_CLOUD_TIMEOUT_{INSTANT,WORKHORSE,DEEP}_MS	30000/120000/300000	Per-tier cloud-attempt timeouts.
INTERN_CLOUD_NUM_CTX	32768	Context-window cap for cloud calls (cloud bills by GPU-time; cap controls cost).

Model availability changes — check, don't assume. Ollama rotates and retires cloud ids server-side, and ollama list is stale in both directions: it keeps listing retired ids and omits live ones. Verified live 2026-09-11: mistral-large-3:675b-cloud (the non-thinking default) plus the thinking flagships deepseek-v4-pro:cloud / kimi-k2.7-code:cloud / glm-5.2:cloud. Gone (HTTP 410) the same day: qwen3-coder-next:cloud — the previous default — along with glm-4.6:cloud, qwen3-coder:480b-cloud, deepseek-v3.1:671b-cloud and gemini-3-flash-preview:cloud. Run ollama-intern-mcp doctor --cloud-check to check your configured ids against the live catalog in-product. A retired id degrades visibly (cloud_model_missing), never silently.

Privacy note. Routing to Ollama Cloud sends prompts to a third party. Ollama's privacy policy states cloud prompts are processed transiently, not retained beyond the request, and not used for training — but it is still egress, which is why it's opt-in and disclosed. Local-only mode (the default) sends nothing off the box.

---

Evidence laws

These are enforced in the server, not the prompt:

• Citations required. Every brief claim cites an evidence id.
• Unknowns stripped server-side. Models that cite ids not in the evidence bundle have those ids dropped with a warning before the result returns.
• ID-validated, not content-validated. Server checks that every cited evidence_ref points to a real evidence id in the assembled set. It does NOT verify that the claim text is derivable from the cited evidence — that is the model's job, and weak briefs sometimes contain unsupported claims with valid refs. Use weak: true + coverage_notes + the included excerpt field to spot-check.
• Weak is weak. Thin evidence flags weak: true with coverage notes. Never smoothed into fake narrative.
• Investigative, not prescriptive. next_checks / read_next / likely_breakpoints only. Prompts forbid "apply this fix."
• Deterministic renderers. Artifact markdown shape is code, not a prompt. draft stays reserved for prose where model wording matters.
• Same-pack diffs only. Cross-pack artifact_diff is refused loudly; payloads stay distinct.

---

Artifacts & continuity

Packs write to ~/.ollama-intern/artifacts/{incident,repo,change}/<slug>.(md|json). The artifact tier gives you a continuity surface without turning this into a file-management tool:

• artifact_list — metadata-only index, filterable by pack, date, slug glob
• artifact_read — typed read by {pack, slug} or {json_path}
• artifact_diff — structured same-pack comparison; weak-flip surfaced
• artifact_export_to_path — writes an existing artifact (with provenance header) to a caller-declared allowed_roots. Refuses existing files unless overwrite: true.
• artifact_incident_note_snippet — operator-note fragment
• artifact_onboarding_section_snippet — handbook fragment
• artifact_release_note_snippet — DRAFT release-note fragment

No model calls in this tier. All render from stored content.

---

Threat model & telemetry

Data touched: file paths the caller explicitly hands in (ollama_research, corpus tools), inline text, and artifacts the caller asks to be written under ~/.ollama-intern/artifacts/ or a caller-declared allowed_roots.

Data NOT touched: anything outside source_paths / allowed_roots. .. is rejected before normalize. artifact_export_to_path refuses existing files unless overwrite: true. Drafts targeting protected paths (memory/, .claude/, docs/canon/, etc.) require explicit confirm_write: true, enforced server-side.

Network egress: off by default. Out of the box the only outbound traffic is to the local Ollama HTTP endpoint — no cloud calls, no update pings, no crash reporting. Opt-in exception: if you enable Ollama Cloud (OLLAMA_CLOUD_PRIMARY=1 + OLLAMA_API_KEY), prompts for the generative tiers are sent to ollama.com over HTTPS with a Bearer key. This is explicit, disclosed, and off unless you set both vars; embeddings still never leave the box. See SECURITY.md §11.

Telemetry: none. Every call is logged as one NDJSON line to ~/.ollama-intern/log.ndjson on your machine. The server itself phones home to nothing.

Errors: structured shape { code, message, hint, retryable }. Stack traces are never exposed through tool results.

Full policy: SECURITY.md.

---

Standards

Built to the Shipcheck bar. Hard gates A–D pass; see SHIP_GATE.md and SCORECARD.md.

• A. Security — SECURITY.md, threat model, no telemetry, path-safety, confirm_write on protected paths
• B. Errors — structured shape across all tool results; no raw stacks
• C. Docs — README current, CHANGELOG, LICENSE; tool schemas self-document
• D. Hygiene — npm run verify (full vitest suite), CI with dep scanning, Dependabot, lockfile, engines.node

---

Roadmap (hardening, not scope creep)

• Phase 1 — Delegation Spine ✓ shipped: atom surface, uniform envelope, tiered routing, guardrails
• Phase 2 — Truth Spine ✓ shipped: schema v2 chunking, BM25 + RRF, living corpora, evidence-backed briefs, retrieval eval pack
• Phase 3 — Pack & Artifact Spine ✓ shipped: fixed-pipeline packs with durable artifacts + continuity tier
• Phase 4 — Adoption Spine ✓ v2.0.1: three-stage health pass hardened corpus (TOCTOU, 50 MB file cap, symlink rejection, atomic writes, per-file failure capture), tool path traversal, observability (semaphore wait events, timeout error context, profile env-override logging, prewarm cold-start signal), test safety (module-load env snapshot across 10 files, tools/call E2E). Troubleshooting handbook + hardware minimums added for operators.
• Phase 5 — M5 Max benchmarks — publishable numbers once the hardware lands (~2026-04-24)

Phase by hardening layer. Pack and artifact tiers stay frozen at 3 and 7. The atom freeze was lifted at v2.1.0 — new atoms require an audit-justified gap, tests, handbook page, and CHANGELOG entry.

---

License

MIT — see LICENSE.

---

Built by MCP Tool Shop