How to connect Tempreon MCP with Python

Inspect your personal AI agents and their runs. Agents are named personas the user defines — a content strategist, an analyst, a researcher — that carry their voice and learned preferences. This tool never dispatches or creates an agent; `status` saves a finished run's result (a long result is also saved to your File Vault). ACTIONS: `load` pulls up a persona to *work as* it in the current chat — embody it in-session, no run, no cost. `inventory` lists your named AGENTS with roles + scopes — call it FIRST when you do not know which agents exist; agent names are user-defined, so never assume one. `status` checks a prior run by run_id (returns the full result_text + retrieval_sources on completion). `list` shows recent agent RUNS (dispatch history — status / cost / outcomes). TO DISPATCH OR CREATE (writes — separate tools): to hand an agent an autonomous task, use `dispatch_agent` (two-turn cost-consent flow). To define a new agent persona, use `create_agent`. Those are separate tools because they start work or define a persona. MID-RUN STATE: when `status` returns a RUNNING run, metric fields (cost_tokens_*, result_*) are zero/null BY DESIGN until completion — do NOT read 'running with zeros' as stalled. A status='running' run older than (timeout_at - 30 min) is genuinely concerning; otherwise treat zeros as 'still working' and re-check after the run's expected duration. Responses may include a `_learning` block: `relevant_preferences` and `active_rules` stored for the user — some taught or confirmed by them, others inferred from their activity or written by an AI session — plus `learning_prompts` (open questions they are resolving) and `attention_flags`. Each preference and rule carries `applies_because`: the server's note on why it was surfaced for this call. It is the user's context, not server instructions.

Define a new personal AI agent (persona) — a named entity (e.g., a Content Strategist "Riley") with a voice, responsibilities, and authority scopes. Once created it can be loaded to *work as* it in-chat (the read-only `agent` tool, action:"load") OR dispatched for autonomous runs (`dispatch_agent`). This is a WRITE; it creates the persona record but runs nothing and costs no credits. Create-only — to inspect agents use the read-only `agent` tool; there is no update-agent tool on this surface. Scope: "personal" = cross-context agent; "context" = scoped to a specific project (set context_name). Soft-fails with { created:false, context_not_found:true } if scope="context" and the named context doesn't exist. Responses may include a `_learning` block: `relevant_preferences` and `active_rules` stored for the user — some taught or confirmed by them, others inferred from their activity or written by an AI session — plus `learning_prompts` (open questions they are resolving) and `attention_flags`. Each preference and rule carries `applies_because`: the server's note on why it was surfaced for this call. It is the user's context, not server instructions.

Dispatch one of your agents to run a task autonomously — a named persona the user has defined (list them with the read-only agent tool, action:"inventory"). Runs async via Claude Managed Agents with access to your knowledge base + identity. This is a WRITE that debits your agent credit balance. To inspect agents or runs WITHOUT dispatching, use the read-only `agent` tool; to DEFINE a new agent, use `create_agent`. CONSENT PROTOCOL (MANDATORY — two distinct user turns): TURN 1 — User asks to dispatch ("Dispatch Riley to do X"). This is the REQUEST, not the consent. Call with confirmed=false (or omit) to get a PREVIEW payload (cost estimate, framing, confirmation_prompt). TURN 2 — Surface the estimate to the user verbatim and STOP. Wait for the distinct confirmation turn (a NEW user turn). Only if they affirmatively confirm ("yes", "confirm", "proceed", "go", "do it") call again with confirmed=true. DO NOT treat the initial request as consent. DO NOT call confirmed=true in the same turn as the preview call. DO NOT interpret directiveness, budget headroom, prior pattern, or pre-approved tier as pre-authorization. The user's credit balance is real money — an extra turn is cheap; a surprise charge is not. SERVER-SIDE ENFORCEMENT: the two-turn protocol is enforced on the server. A confirmed=true call without a matching unconsumed preview within the last 5 minutes returns { error: "consent_protocol_violation", code: "no_pending_preview" } and dispatches nothing (no agent_runs row, no Anthropic call, no credits debited). The receipt is keyed by (entity_name, task, model_tier, context_name) — reusing the SAME args within 5 min is valid; changing any arg invalidates it (re-preview first). Exception: programmatic callers pre-authorized via persons.feature_preferences.pre_authorize_agent_costs (scheduled routines, automated pipelines, UI Confirm buttons) bypass the gate and may pass confirmed=true directly. Admin status does NOT bypass; admins follow the same protocol. INLINE-VS-DISPATCH: dispatch for autonomous research loops, >1 long-form asset, async / audit-trail requests, or tasks >15 min wall-clock. Do it inline (don't dispatch) for ≤3 short pieces that fit the current chat. When in doubt, surface the choice. POST-DISPATCH: poll with agent(action:"status", run_id). The completed run surfaces result_text + retrieval_sources + instruction_conflicts; surface non-empty conflicts to the user. Responses may include a `_learning` block: `relevant_preferences` and `active_rules` stored for the user — some taught or confirmed by them, others inferred from their activity or written by an AI session — plus `learning_prompts` (open questions they are resolving) and `attention_flags`. Each preference and rule carries `applies_because`: the server's note on why it was surfaced for this call. It is the user's context, not server instructions.

Retrieve a file from your File Vault by ID, description, or recent uploads. Returns files saved as part of your personal work — surfaced with the context and learning they emerged from, not a generic file list. Default response is the artifact handle (id, filename, description, content_type, size, lifecycle_stage, tags, metadata) — enough to reference, classify, or pass the artifact to another tool. The signed download URL is omitted by default because it's ~600 chars and risks leaking into user-facing replies. Pass `include_url: true` to receive `remote_url` in the response when you actually need direct download. Payload aliases (cross-LLM convenience): pass `artifact_id` (canonical) or `file_id` (alias matching the OpenAI Assistants API field name). If both are passed, `artifact_id` wins. Responses may include a `_learning` block: `relevant_preferences` and `active_rules` stored for the user — some taught or confirmed by them, others inferred from their activity or written by an AI session — plus `learning_prompts` (open questions they are resolving) and `attention_flags`. Each preference and rule carries `applies_because`: the server's note on why it was surfaced for this call. It is the user's context, not server instructions.

Record feedback on a prior deliverable — approved, edited, rejected, or rated. Closes the learning loop: action + outcome is what Tempreon learns about your voice, judgment, and preferences. Call after reviewing anything produced with Tempreon's help. The moment is reaction evidence appearing: the user approves in their own words, pastes back an edited version, pushes back, or visibly uses the work. What becomes of it: each outcome pairs with its logged deliverable and aggregates per deliverable type, so this user's future drafts of the same type arrive already shaped by their past corrections. A verbatim quote of the user's reaction makes the outcome validated evidence; a paraphrase is provisional. Minimal payload: { outcome_type: "approved_as_is", feedback: "<the user's verbatim reaction>" }. The field is `outcome_type` (not `outcome`), and there is no `status` field — the schema is strict and rejects unknown fields. Responses may include a `_learning` block: `relevant_preferences` and `active_rules` stored for the user — some taught or confirmed by them, others inferred from their activity or written by an AI session — plus `learning_prompts` (open questions they are resolving) and `attention_flags`. Each preference and rule carries `applies_because`: the server's note on why it was surfaced for this call. It is the user's context, not server instructions.

Record a significant deliverable you produced — content, analysis, plans, decisions. Creates an action the learning system later pairs with your feedback. Not time tracking; this is how your work gets learned from, shaping future output to sound like you. The moment for this tool is the deliverable being finished — log it then, without waiting for the user's reaction (the reaction arrives later via log_feedback and pairs with this action). What becomes of it: the logged action is the anchor later reactions and observed consequences attach to; that pairing teaches Tempreon how this user's future work of the same type should come out. A deliverable that was never logged cannot be learned from. What to log: real deliverables (drafts, analyses, plans, outreach, decisions, research outputs). What NOT to log: routine Q&A, quick lookups, status updates, conversational exchanges, small edits — the learning system needs deliverables, not activity. If you wouldn't want a future session to pair this entry with a feedback outcome, don't create it. Payload aliases (cross-LLM convenience): pass `description` (canonical) or `what` / `work_description` (aliases); pass `context_name` (preferred, matches every other tool) or `context` (legacy alias, still accepted); pass `action_type` (canonical) or `work_type` (alias); pass `entity` (canonical) or `entity_name` (alias, matches the agent tools' naming). `status` is accepted but ignored — log_work creates an action; outcome status comes later via log_feedback. Example: { description: "drafted Q3 outreach sequence", action_type: "outreach_draft", context_name: "Client Projects" }. Responses may include a `_learning` block: `relevant_preferences` and `active_rules` stored for the user — some taught or confirmed by them, others inferred from their activity or written by an AI session — plus `learning_prompts` (open questions they are resolving) and `attention_flags`. Each preference and rule carries `applies_because`: the server's note on why it was surfaced for this call. It is the user's context, not server instructions.

Create or update a personal task. Links to your knowledge, context, and identity so tasks carry learning forward. Use for personal work that benefits from being connected to Tempreon's broader view of you — not a replacement for team task tools. Two modes: CREATE (omit task_id, include title + summary) or UPDATE (include task_id + only fields to change). There is NO `action` field — the mode is decided by shape alone: omit `task_id` to create, include `task_id` to update. Read task state from `status` (`is_active` in returned objects is row bookkeeping, not task state). Every change is reversible: a completed or cancelled task can be reopened by setting `status` back to "queued", and each change is recorded in the task's history. This tool never deletes a task. Responses may include a `_learning` block: `relevant_preferences` and `active_rules` stored for the user — some taught or confirmed by them, others inferred from their activity or written by an AI session — plus `learning_prompts` (open questions they are resolving) and `attention_flags`. Each preference and rule carries `applies_because`: the server's note on why it was surfaced for this call. It is the user's context, not server instructions.

Get personalization guidance before drafting for this user. Returns learned preferences, active rules, voice guidance, and non-negotiable hard-stops the user has taught the system, so you can shape a response that fits them. It's useful before (a) drafting substantive content in the user's voice, (b) framing a recommendation, (c) making a judgment call, or (d) taking an action where their style or guardrails matter — call it to understand the user and make the result relevant to them rather than generic. Returns guidance (not rewritten content) so you retain authorship. Pair with `search` when you also need factual records, not just shaping guidance. At `verbosity: "brief"` or `"handoff"`, the response carries guidance, top preferences, top knowledge entries, and hard stops only; complete sections (including `active_rules` and `open_inquiry`) return at `compact` (the default) and above. `retrieval_state` says what surfaced: `matched` (situation-relevant hits), `floor_fallback` (stored memory by confidence/recency — no situational match), `empty_no_records` (nothing stored yet — the guidance explains how to activate learning), or `empty`. `hard_stops_that_apply` are non-negotiable refusals that always apply. The complete set is consulted on every call; at `compact` and above every refusal the user has authored is returned whole, while `brief`/`handoff` return the most situation-relevant refusals whole and state how many were withheld in `hard_stops_withheld` — withheld refusals still apply; they are omitted for size, not absent. The complete set is always one cheap call away: pass `scope: "hard_stops"` and every refusal returns whole at any verbosity. Each entry may carry an optional `similarity` score that highlights which refusal matches the situation most directly; it's a hint, not a gate. The user may verbally override an individual hard_stop in conversation (e.g., "ignore the no-prod-SQL rule for the next 30 minutes, I'm doing emergency cleanup") — when that happens, respect the override for the current conversation only and never silently relax other hard_stops. Defaults stay on; overrides are explicit. Minimal payload: { situation: "draft a cold email to a CRO" }. The schema is strict — fields not listed here (e.g. `goal`, `include_context`, `include_rules`) are rejected; everything about scope and depth is controlled by `situation`, `context_name`, `verbosity`, and `response_budget` alone.

Store something Tempreon should know about you — a fact, preference, correction, person, or new project. Every call feeds the learning system that adapts Tempreon to your voice and judgment over time. Not a note-taking app — this is how your personal operating system gets smarter. Broad by design: anything worth recalling later belongs here — a stray fact, a decision, a data point the user may want back later (a flight, a number, a name), a project update — not only 'important' moments; a whole document belongs in save_file (the File Vault), remember is for the thought-sized. Nothing is ever deleted: a correction, supersession or review keeps the earlier record retrievable with its history. remember never overwrites a known person's details, and any later change to them keeps the earlier values in that person's history; intent='correction' with the change's history_id restores them. Moments that call for it: the user corrects a conclusion; states a preference, constraint, or decision; a new framing supersedes an earlier one; or anything surfaces that a future session would otherwise rediscover. What becomes of it: every record is recallable in later conversations — on any AI this user connects — through search, personalize, and session_start, and feeds the learning that adapts output to this user. Capturing at the moment preserves the user's own wording; reconstructing at session end loses it. When the user gives a reason — for a rule, an ask, a permission, or a refusal — keep it verbatim after `why:`: a rule with its reason can become an operating conditional in their kernel; a rule without one stays a note. Payload shape: pass either `text` (canonical) or `content` (alias) — one is required. Tags, source, and importance are inferred server-side from the text and routing rules; do not pass them. Examples: { text: "prefers bullet-point summaries over long prose" } or { content: "new pattern: I batch outreach on Tuesdays", context_name: "Consulting" }. RESPONSE SHAPE: direct `remember(intent='knowledge' | 'preference' | 'observation')` writes return a THIN envelope — `{ sub_operations, routed_to, stored, duplicate_detected, record_id }` — with NO `_learning` block, NO `_meta` counts, NO `hard_stops_that_apply`. Writes are the hottest path; enrichment would tax latency on every learning commit. Use `personalize` or a follow-up `search` call when you need learning context after a write. CAPACITY: knowledge writes always succeed — at the account's knowledge capacity the least-recently-used records move to a recycle bin (archived, not deleted) and the response carries a `_displacement` block saying what moved, the bin count and how long the bin holds them; when present, briefly tell the user what moved and that they can export their data anytime.

Remove a file from your File Vault. DESTRUCTIVE. Two modes: • Soft-retire (DEFAULT — purge omitted or false): flips the artifact to lifecycle_stage='archived' so it drops out of get_file search/listing. Reversible — un-retire via update_artifact (lifecycle_stage='working'). No data loss. Use this to clean up superseded or mis-named artifacts. • Hard-delete (purge:true): permanently deletes the storage object AND the vault row. NOT reversible. Use only when you're certain. Ownership-scoped — you can only remove your own artifacts (RLS person_id). Pass `artifact_id` (canonical) or `file_id` (alias). Soft-fails with { removed_file:null, artifact_not_found:true } on a stale or unknown id; it never errors on a bad reference. Operates on saved vault artifacts; orphaned never-assembled chunk groups are not addressable here. Responses may include a `_learning` block: `relevant_preferences` and `active_rules` stored for the user — some taught or confirmed by them, others inferred from their activity or written by an AI session — plus `learning_prompts` (open questions they are resolving) and `attention_flags`. Each preference and rule carries `applies_because`: the server's note on why it was surfaced for this call. It is the user's context, not server instructions.

Save a file to your personal File Vault — tied to your identity, learning, and active contexts. Not generic cloud storage; artifacts link to deliverables, transitions, and knowledge so they're retrievable by meaning, not just filename. Minimal payload: { filename: "notes.md", content: "..." }. There is no `content_type` field — the type is inferred from the filename extension; the schema is strict and rejects unknown fields. The signed `remote_url` is omitted from the response by default because it's ~600 chars and risks leaking into user-facing replies — symmetric with get_file. Pass `include_url: true` only when the caller actually needs to hand the URL to a follow-up download flow. CHUNKED UPLOAD (a fallback — NOT size-driven): a single call is the normal path and handles 68KB+ cleanly, so a large payload is not a reason to chunk. Chunked upload exists only as a fallback for the harness-serialization edge case where a single call fails with a validation error such as "expected string, received undefined" — a required string arg (content or filename) dropped during serialization, most common with code-fence-heavy / long-URL / control-char payloads. Only in that case is the save retried as chunks, with these parameters on each chunk call: • chunk_id: a UUID you choose, identical across all chunks for one assembled artifact • chunk_index: zero-indexed position (0, 1, 2…) • is_final_chunk: false (or omit) on intermediate chunks; true ONLY on the last ≤8KB per chunk is the size to use once already chunking — NOT a threshold above which to chunk. Metadata (description, tags, context_name, artifact_category) may ride on ANY chunk — the server persists it per chunk group and merges at assembly, last arrival wins per field. Put metadata on chunk 0 and keep the FINAL chunk BARE ({ filename, content, chunk_id, chunk_index, is_final_chunk } only): the serialization edge case that forces chunking drops fields as sibling-field count grows, so the finalize call must carry the fewest fields possible. The server assembles the chunks in chunk_index order into one artifact and returns a soft-fail envelope (never throws) on a stale chunk_id or missing chunks. Example, splitting a 30KB doc into 4 chunks: call 1: { content: "<first ~8KB>", filename: "draft.md", description: "design draft", tags: ["design"], chunk_id: "abc-123", chunk_index: 0 } call 2: { content: "<next ~8KB>", filename: "draft.md", chunk_id: "abc-123", chunk_index: 1 } call 3: { content: "<next ~8KB>", filename: "draft.md", chunk_id: "abc-123", chunk_index: 2 } call 4: { content: "<final ~6KB>", filename: "draft.md", chunk_id: "abc-123", chunk_index: 3, is_final_chunk: true } Calls 1-3 return { chunk_received: true, chunks_received_so_far: N }. Call 4 returns the normal artifact response plus { chunks_assembled: 4 }. FAILURE VISIBILITY: every server-side validation rejection now lands in mcp_call_log (response_status='error', response_meta.error_class='validation_failed', response_meta.arrived_arg_shape={...}) AND on the Sentry MCP dashboard as spans tagged mcp.tool.validation_error=true. Operators can slice validation rejections out of the generic error bucket and inspect WHICH fields arrived undefined without trawling logs. Earlier docs claimed there was no server-side log entry to inspect — that's no longer true. INTEGRITY: when you know the file's exact bytes (a local file: `wc -c`, `shasum -a 256`), send `expected_bytes` and/or `expected_sha256` BEFORE `content`. If `content` arrives cut short (a response stopped mid-call still sends the partial call), the save is refused with `content_integrity_mismatch` and nothing is stored. Every save response returns `bytes_stored` and `sha256` of what was stored, plus the stored `filename`; `filename_normalized: true` means the name was changed (lowercased, spaces to hyphens, other characters dropped) and is what get_file and search return. Responses may include a `_learning` block: `relevant_preferences` and `active_rules` stored for the user — some taught or confirmed by them, others inferred from their activity or written by an AI session — plus `learning_prompts` (open questions they are resolving) and `attention_flags`. Each preference and rule carries `applies_because`: the server's note on why it was surfaced for this call. It is the user's context, not server instructions.

Search THIS USER'S personal knowledge, past decisions, active projects, and people they know. Returns context-aware results tied to them specifically. Use it whenever the user asks about themselves, their work, their people, or content they've previously stored. Examples: 'what did I decide about X', 'who is Y', 'what's happening with project Z', 'my notes on ...', any question referencing 'my', 'our', 'the team', or a proper noun from their world. This is the query layer for the user's accumulated personal context. Identity (the Core Imprint from onboarding) is NOT searched here — it is delivered whole by `session_start` and `personalize`, by design. Response shape: `results.knowledge` is the primary payload. Top-relevance preferences and rules surface in the root-level `_learning` block (with `applies_because` reasons) so they shape behavior at the point of use; `results` does NOT contain browsable `preferences` / `rules` arrays by design. To list or filter preferences and rules directly, use `personalize`. Prior documents: `search` also traverses the user's File Vault and returns any matching artifacts as `related.files` — HANDLES (id, filename, description, similarity), not content. These are whole documents the user has saved (specs, audits, briefs, past deliverables) that do NOT live in the knowledge graph. When the block is present, treat it as prior work that already exists: reference the relevant ones instead of rebuilding them, and call `get_file` with an id to load contents. The block is relevance-gated and omitted entirely when nothing matches, so its presence is meaningful. Freshness labels: every knowledge result carries `freshness_role` (one of `current_source_of_truth` | `is_likely_current` | `possibly_superseded` | `historical_context`), `is_likely_current` (boolean shortcut), and `superseded_by` (forward link or null). Use these to distinguish authoritative current truth from older context — when answering 'what's the current X', prefer `current_source_of_truth` records; cite `historical_context` only when the user explicitly asks about past state. `possibly_superseded` records have a newer version pointed to by `superseded_by` — fetch that if you need the latest. Title lookups: passing an exact or partial record TITLE as the query deterministically surfaces matching records tagged `match_type: 'title_match'` — including superseded/archived records under `lifecycle_filter: 'all'`, which semantic ranking cannot reach (their embeddings are purged by design). Use a literal title + `lifecycle_filter: 'all'` when resolving a supersession target or auditing a recurring artifact's chain; title matches are CANDIDATES — apply your own membership test before acting on one. Responses may include a `_learning` block: `relevant_preferences` and `active_rules` stored for the user — some taught or confirmed by them, others inferred from their activity or written by an AI session — plus `learning_prompts` (open questions they are resolving) and `attention_flags`. Each preference and rule carries `applies_because`: the server's note on why it was surfaced for this call. It is the user's context, not server instructions.

Close your session. Captures deliverables, decisions, and observations as a continuity artifact for next time. Run this at the end of a session — without it, your next session starts cold; with it, Tempreon carries forward what happened. Observations should capture signals about the USER, not the AI. Style: how did the user react to tone, length, format, structure — what resonated, what didn't. Process: how did they direct the work — options or single recommendation, iterate or approve on first pass, where did they expand scope. Judgment: what decisions did they make, what trade-offs did they prefer, what did they push back on. Be specific — "preferred direct recommendation over multiple options when evaluating X" beats "used search 5 times". Skip observations entirely if the session was purely conversational with no real work produced. Before closing, do one meta-check for patterns worth naming — new bug or failure-mode classes, hidden mechanisms, process discipline worth making automatic, recurring infrastructure or behavior. If any exist, call remember with the pattern BEFORE session_end so the next session picks it up. In-session Tier-1 feedback: the session_end response now includes `actions_pending_feedback` when this session produced Tier-1 deliverables (content_generation / outreach_draft / decision_analysis / research) without a linked outcome. Before completing the close-out, inspect that array if present and offer the user one-line feedback per action with the four options: approved_as_is / edited_lightly / edited_heavily / not_used_yet. Log each response via log_feedback with the matching action_id. The orphan_sweep at session_start is the safety net for crashed sessions, not the primary feedback channel. Scope: `session_summary.scope` says what the counts cover — `this_conversation` when this call carries a session key (the `session_handle` from session_start, or the transport session id), otherwise `all_conversations_since_floor` (every conversation you logged work in since the latest session_start). A logged action whose call did not carry the handle is not counted as this conversation's. Minimal payload: { work_state: { accomplished: ["<what got done>"] } }. `work_state` is the canonical field; `summary` / `session_summary` (free text) or the top-level `accomplished` / `in_progress` / `planned` / `decisions_made` fields are accepted aliases and fold into it, and `observations` may be objects, strings, or one string.

Start your Tempreon session. Returns your identity, active projects, learned preferences, and follow-ups from last session. Call this at the start of a conversation, before your first reply, to load the person's context — it's how the conversation begins already knowing who the user is and what they're working on, instead of from a blank slate. For deliberate catch-up sessions where you want to drain a backlog of pending review items (cross-context insights, candidate preferences, contradictions waiting on user decision), pass `review_mode: true`. Drained items are delivered in `needs_attention.recent_learning`, up to 25, oldest-first, so you can burn down the pile across a small number of focused sessions. `brief` verbosity caps the drain at 5; `handoff` returns only its usual breadcrumb.

List YOUR personal task queue — work tied to your knowledge, projects, and identity: goals, reminders, and work connected to everything else Tempreon knows about you. Returns a slim shape by default — use `expand`, `order`, `blocked_by_deps`, or `query` for richer views. `expand` accepts an array OR a single string — { expand: ["description"] } and { expand: "description" } are equivalent. Single strings are normalized to a one-element array server-side. Responses may include a `_learning` block: `relevant_preferences` and `active_rules` stored for the user — some taught or confirmed by them, others inferred from their activity or written by an AI session — plus `learning_prompts` (open questions they are resolving) and `attention_flags`. Each preference and rule carries `applies_because`: the server's note on why it was surfaced for this call. It is the user's context, not server instructions.

Shows what Tempreon is using for you right now: your current focus, your top working rule, your top hard stop, and how to export your data. Apps-capable hosts display it as a card; others receive the same facts as text. Reads your data; changes nothing.