MCP-Referenz
Sonaloop ist MCP-first — die Tools sind die API.
Sonaloop ist MCP-first — die Tools sind die API (251 Tools, automatisch aus den Live-Modulen generiert). Konvention: brief_* sammelt Kontext, dann autort der Agent, dann validiert + persistiert record_* / put_*. Beginne mit der Resource sonaloop://guide/research für den kanonischen Pfad.
Eine Studie fahren44
Der Container, die Plan-Engine und die Methodik.
Evidenz & Reports60
Councils, Prototypen, Notizen — und die Reports, die sie verdichten.
Personas & Erinnerung
Personas13Personas anlegen und in echten Quellen erden.
assess_coverageCoverage / diversity check over a study's PERSONA SET — a deterministic analysis that flags when the panel is too narrow to be trustworthy (a homogeneattach_evidenceAttach a real-world SOURCE (doc/url/note) to a persona to ground its claims.brief_personaGather the prompt + frame to AUTHOR one persona profile from a source description. You write the profile JSON from `instructions`, then call record_peexport_personaExport one persona (profile + SOUL/memory) as json/markdown.generate_avatarGenerate (or regenerate) the persona's avatar image — needs OPENAI_API_KEY. Without the key this degrades gracefully (in-band note, no error).get_personaFull persona record + recent calendar/experience/pain points.get_persona_soulThe persona's SOUL.md (authoritative identity + grown drift).list_personasLean one-line overview of personas (slug/name/age/role/segment) — drill in with get_persona for the full profile. Pass compact=False for full profilesprepare_persona_agent_contextBuild the launch context for a persona subagent (SOUL + state + recent events).record_personaValidate + persist the persona profile you authored from brief_persona. This is the create path (no server-side text generation).refresh_persona_from_sourceRe-derive a persona's rendered SOUL/profile artifacts from its stored source record.suggest_tech_comfortThe CANONICAL tech-comfort vocabulary for a persona's capability profile (capabilities.tech_comfort) — call this before declaring/patching one. Each iupdate_personaApply a host-authored patch to a persona's profile; records a revision with the reason. A `capabilities` patch ({rungs:{see,walk,drive,login}, tech_coSimulation & Erinnerung30Tage/Monate simulieren und Persona-Erinnerung abrufen.
brief_consolidationGATHER a simulated day + known entities. Returns instructions for you to author memory_deltas (entities/facts/threads/event_links); then record_memorybrief_dayGATHER context for planning ONE day (active projects, open threads, recall, world). Returns instructions for you to author a day plan; then put_day_plbrief_digestGATHER a period for a consolidated digest (replaces hardcoded reflections).brief_monthGATHER context to author a whole month bundle (period plan + sample days + digest), chained on the prior month. Then record_month_bundle.brief_periodGATHER context for a week|month|quarter|year plan, incl. candidate sample days. Author a period plan (with sample_days) then put_period_plan. Trends oextract_pain_pointsSurface a persona's pain-point observations over a date range.get_activityFetch one simulated activity (block) by id.get_calendarA persona's calendar events for one day.get_calendar_periodA persona's calendar for a day|week|month view.get_current_stateA persona's live state — what they're doing now / at a given time.get_day_planFetch the stored day plan for a persona on a given date.get_open_loopsA persona's unresolved threads / open loops (filter by status).get_period_planFetch a stored period plan (week|month|quarter|year) for a persona.get_persona_memoryRender + return MEMORY.md: active projects (timelines), open threads, digests.get_projectFull fact/status timeline of one project (use `as_of` for how it looked then).get_state_atTime-travel: entities + facts + open threads + world valid at a given date.get_timelineChronological experience events for a persona over a date range (optionally one entity).list_active_projectsCompact list of the persona's open projects with status + open-loop counts.list_digestsList a persona's consolidated digests (optionally filtered by scope).list_period_plansList a persona's period plans (optionally filtered by scope).put_day_planPersist the day plan you authored from brief_day.put_digestPersist + embed the digest you authored from brief_digest.put_period_planPersist a period plan (its sample_days drive which days you simulate concretely).recall_memoryHybrid (semantic + keyword/entity + recency + importance) recall over episodes, facts, digests, threads. USE when you want to check if the past has sorecord_dayPersist a host-authored SINGLE day end-to-end (put_day_plan -> simulate the authored blocks/activities -> optional consolidation). See brief_day's `darecord_memory_deltasPersist host-authored memory deltas: resolves/dedupes entities, writes bi-temporal facts (invalidating superseded status), opens/resolves threads, linrecord_month_bundlePersist a host-authored month bundle through the full loop (plan->sample days-> simulate->consolidate->digest->embed).resolve_entityResolve a free-text mention to an existing entity (dedup), or null if new.search_entitiesFind a persona's memory entities by kind and/or name substring.summarize_persona_periodGather a persona's experience over a date range (optional lens) for summarisation.Eine Studie fahren
Projekt-Graph & Report14Der Studien-Container, sein Graph und der finale Report.
brief_synthesis_outlineGATHER the whole project graph + study content so you can author the project REPORT outline.brief_synthesis_sectionGATHER one section's source studies (+ councils) so you can author it with citations.create_research_projectCreate a research Project: a themed GRAPH of studies (syntheses). Distinct from the memory get_project (a persona's own work project).delete_councilDelete a council session.delete_personaDelete a persona + all its persona-scoped rows and rendered SOUL/avatar files.delete_research_projectDelete a project container + its edges/open-questions. Syntheses (incl. reports) are kept.delete_synthesisDelete a synthesis (study) and detach it from any project graphs.get_project_graphThe core navigation call: nodes (studies + theme tags + sentiment), typed edges, themes, build order, and open questions for one research project.get_research_frontierThe anti-explosion surface: the project's still-open questions + structural notes.list_research_projectsList research projects (graph containers) with study/edge/theme counts.record_open_questionsPromote open questions raised by a study into first-class graph nodes.record_synthesis_outlinePersist the host-authored report outline (sections derived from the graph).record_synthesis_sectionPersist one authored report section. `content`: {markdown, citations:[{study_id|council_id}], figures:[…]}. Figures can embed a chart — {kind:'chart',suggest_chart_kindsWhich report CHART to use when (bar, pie, stacked_bar, diverging_bar, gauge, dot_plot, heatmap, line, effort_impact) + each one's author payload shapePlan & Steuerung18Projekt anlegen und die Analyze→Act→Verify-Schleife fahren.
add_taskInsert a task into the plan (shape the breadth): bucket analyze|act|verify, a capability tag, consumes (DAG edges), optional gates. Returns the createassess_progressRecord an evidence-backed assessment of progress toward the HMW goal. `delta` is a free host judgment (never a number); a non-binding coverage snapshoassess_projectProject-level meta-assessment (read-only, computed — no LLM verdict): coverage, open evidence gates, open questions, a saturation hint, structural gapcheckpoint_stepAppend a completed step (task_id, bucket, key, evidence ids, 1-line summary) to the journal.complete_taskMark a ready task done. Verify tasks are gate-checked (breadth + gate judgment + artifacts/ sessions) and rejected until satisfied.export_plan_mdRender the plan as a human-readable, bucketed plan.md (analyze/act/verify + status + gates).finish_runMark the run finished/stopped.get_planThe project's research plan (analyze/act/verify task DAG + evidence refs + judgments).inject_workTurn one critic `missing` item {kind, what, ...} into a real plan task/open-question (the driver does this automatically; exposed for manual gap-filliiterate_taskOpen the NEXT iteration round on a done-or-ready task with a `loop_back` target (HOST-judged — the engine never loops on its own): clones the loop-baclink_evidenceAttach an evidence ref (kind=council|synthesis|artifact|session, id) to a task (usually the act task whose run-council/scaffold/session just produced next_actionThe ready task FULLY loaded for a lean autonomous loop: analyze→grounding (prior syntheses + open questions); act→the consumed frame's framed questionrecord_critic_roundLog one completeness-critic round on the run (loop-until-dry observability).record_frameDischarge an ANALYZE frame task: author research questions + hypotheses grounded in cited persona memory (>=1 question + >=1 memory_ref). Understand brun_journalThe run's journal (steps + critic rounds + cursor + status) — the source of truth for resume.run_stepThe ESV driver's brain (deterministic). Returns the next dispatch to execute: {kind: analyze|act|verify, step_id, key, next_action, directive} → spawnstart_projectTHE ENTRY POINT. Create a project + seed its research plan (methodology -> analyze/act/verify scaffolding; none -> one dischargeable root frame task);start_runCreate (or resume) the run object that the driver advances over the plan. Returns the run + its journal; pass an existing run_id to resume (idempotentMethodiken12Die Phasen-Konstellation einer Studie wählen oder bauen.
brief_nextGATHER what the plan's ready frontier needs now: the primary ready task (+ the full ready set), its bucket/capability, consumed frames, and unmet gatedescribe_frameworkOne Framework's plain-language description by stable id (e.g. 'double_diamond'): {id, name, what, when, stages:[{id, name, what}]}. The structured comget_methodologyThe full constellation spec for one methodology (steps, tags, consumes, produces, requires).list_frameworksThe Frameworks (the methodologies that seed a study's plan) in PLAIN LANGUAGE, as one clean list the user — and the website / job presets — can read: list_methodologiesList available methodologies (built-in + user-defined) and their step keys.record_judgmentRecord an evidence-backed LLM gate judgment on a plan TASK (usually a verify task). `gate_tag` is a FREE tag (e.g. divergence_complete, or whatever thregister_methodologyRegister a USER-DEFINED methodology — author your own constellation and it becomes a Framework any study can run through (start_project(methodology=<kset_project_methodologyBind an existing research project to a methodology by (re)seeding its plan from the constellation. The plan is the single engine; drive it via the plasuggest_artifact_typesSUGGESTED artifact-type tags for produces.artifact_type / requires.*_tags (matched by tag-equality, no string is special-cased). Recommendations only.suggest_capabilitiesSUGGESTED capability tags (explore/cluster/decide/build/test/synthesize, …) for a step's `tags`. Recommendations only — adopt, tweak, or invent your osuggest_methodologiesSUGGESTED whole-constellation templates to copy and adapt (the registered methodologies + any extra templates). Tags are free; nothing here constrainssuggest_rolesSUGGESTED role tags for a step's produces.role. Recommendations only.Evidenz & Reports
Councils & Reports28Persona-Debatten abhalten und zu Reports verdichten.
add_artifactBring a REAL artifact into a project's council pool so personas react to what is ACTUALLY there — a live URL/website, a prototype link (kind='prototypbrief_askGather one persona's loaded context (SOUL + recent events + task-keyed memory) so you can author an honest, in-character answer. No server-side generabrief_councilGather a council. A council is scoped to a research project, so `project_id` is REQUIRED (create one first with create_research_project; personas are brief_head_to_headGather a HEAD-TO-HEAD (X vs Y) — run the panel on a DIRECT comparison of two (or more) concrete options and get a reasoned, segmented preference, NOT brief_price_ladderGather a PRICE LADDER (pricing Job protocol — willingness-to-pay): a FIXED ascending ladder of price points every persona reacts to, one van-Westendorbrief_red_teamGather a RED-TEAM (falsification) — run the panel to ATTACK the idea instead of flattering it ("why would this segment NOT adopt / NOT pay / churn?"),brief_synthesisGATHER an ordered chain of councils (their exec_summaries/votes) so you can author a cross-council synthesis (arc, gesamtbild, recommendations, positidelete_artifactRemove an artifact (by id or label) from a project's pool.export_council_sessionExport one council session as a document (md|json) for sharing.export_synthesisExport a report (synthesis). format: `md`|`json` returned inline · `pdf`|`pptx` rendered as a presentation-grade file written to disk (returns its patexport_synthesis_htmlExport a report (synthesis) as a SHAREABLE read-only static HTML bundle — `data/export/share/<token>/index.html`: the exact inspector document minus aget_artifactOne artifact (by id or A/B label) with its full captured snapshot.get_councilFetch one council session by id (prompt, turns/statements, votes, summary).get_head_to_headFetch one head-to-head result by session id — its options, per-persona preferences, the deterministic aggregate (preference + margin + abstentions + sget_price_ladderFetch one price-ladder result by session id — the ladder, the raw per-persona/per-rung banded responses (persona, price point, band, quote) and the deget_red_teamFetch one red-team result by session id — its stance, adversarial roles, per-persona objections and the deterministic case-against (themes grouped by get_synthesisFetch one report (synthesis) by id — its findings/sections/scope and metadata.list_artifactsList every artifact ingested into a project (id, label A/B/…, kind, url, capture status).list_councilsList council sessions (id, prompt, persona count, votes), newest first. Paginated per the shared convention (docs/pagination.md): `limit` (default 25)list_synthesesList all reports (syntheses) — id, title, scope, date — for browsing.price_ladder_analysisThe analytics shape of a recorded price ladder: acceptable-price range + cliff points, overall and one row per segment (pricing protocol step range_anrecord_councilPersist a host-authored council. Shape it by what you pass (the UI derives the mode): DISCOVERY = `questions` (open user-research questions), NO proporecord_head_to_headPersist a host-authored HEAD-TO-HEAD (stored as a CouncilSession with a `head_to_head` block). Pass the labelled `options`, each persona's `preferencerecord_price_ladderPersist a host-authored PRICE LADDER (stored as a CouncilSession with a `price_ladder` block). `responses` is the structured willingness-to-pay payloarecord_red_teamPersist a host-authored RED-TEAM (stored as a CouncilSession with a `red_team` block). Pass the per-persona `objections` ([{persona_id, theme (a shortrecord_synthesisPersist/UPDATE a host-authored synthesis. A synthesis is DECOUPLED from councils: `council_ids` is OPTIONAL (may be empty — affinity over notes, a synsuggest_finding_kindsSUGGESTED Finding kinds (summary/key_problem/pain_solver/open_question/recommendation/ cluster/segment/shortlist/ranking/pain_point) for a `findings` suggest_stancesThe CANONICAL stance vocabulary — call this before authoring statement stances, votes, or head-to-head/red-team reactions. Every stance is {value -2..Prototypen & Tests14Lauffähige Mocks bauen und von Personas benutzen lassen.
brief_prototype_sessionGATHER persona context + how-to-drive + anti-steering before a persona uses the app.delete_prototypeDelete a prototype artifact record (files on disk are kept).get_prototypeOne prototype artifact by id or slug.list_proto_sessionsList live browser sessions.list_prototypesList registered prototype artifacts (optionally for one project).proto_actAct on the latest snapshot: {type: click|type|select|scroll|key|wait, ref?, text?, value?}.proto_closeClose a browser session.proto_openOpen a real running app in a headless browser session; returns {session_id, snapshot}. Without the optional browser harness this degrades gracefully (proto_readRe-read the current snapshot of a session.record_prototype_sessionPersist a persona's grounded prototype use as an experience + memory + artifact; rejects claims with no matching observed state in the session log. `rregister_prototypeRegister a hand-authored app under prototypes/ as a runnable artifact (fidelity tag, e.g. lofi|midfi|hifi).run_prototypeStart the app on an ephemeral localhost port; returns {url, pid}. Local-only.scaffold_prototypeGenerate a real, minimal, runnable web app from a host-authored concept and register it. The app is genuinely clickable (real DOM) for Playwright. Thestop_prototypeStop a running prototype.Notizen & Struktur18Signale festhalten und Knoten in Sections gruppieren.
add_to_sectionAdd node ids to a section's membership (validated against the project graph).create_noteCreate a lightweight NOTE node — the ONE note entity (from a raw observation to a worked-out solution idea; there is no separate 'concept'). For a solcreate_sectionCreate a labeled overlay grouping of graph nodes (e.g. 'Initial user research', 'Problem exploration'). `member_ids` must reference real nodes (councidelete_noteDelete a note node from the project.delete_sectionDelete a section. Member nodes are kept (reference, not containment).derive_sectionsAuto-organize: derive persisted SECTION overlays from the plan — one per methodology phase (fan + its converging waist; label from the step name), a Pexport_sectionSelf-contained export of a section (md|json): its members' summaries, for a downstream agent.get_sectionGet one section by id.get_section_membersResolve a section's members into {kind,title,summary,href} records (section-scoped view).list_notesList a project's note nodes in creation order. Paginated per the shared convention (docs/pagination.md): `limit` (default 25) + opaque `cursor`; answelist_sectionsList a project's sections (ordered).remove_from_sectionRemove node ids from a section's membership (nodes themselves are untouched).reorder_sectionsSet the display/outline order of a project's sections.scaffold_synthesisSeed a project REPORT outline from the project's phases so the conclusion hand-off is one author step (brief_synthesis_section → record_synthesis_sectset_note_dataMerge keys into a note's `data` — e.g. set a concept note's `prototype_id` once you build it, so the completeness critic stops flagging it as un-protoset_section_membersBulk-set a section's membership — the 'promote this cluster into a named section' move.suggest_section_kindsSuggested section kinds + presentation (data-driven; adopt/tweak/invent).update_sectionUpdate a section (title/kind/parent_id/order/presentation/note/member_ids).Evaluation
Evaluation & Kritik21Runs bewerten und Abdeckung/Qualität kritisieren.
brief_cohort_criticGATHER compact per-persona records across the cohort so you can judge which personas fall OUT of the cohort's range (relative outliers / clones). Thenbrief_completeness_criticGATHER a computed exhaustiveness snapshot for an INDEPENDENT critic: coverage + the generative breadth_candidates (segments/angles/concepts/risks/fidebrief_eval_criticGATHER source+SOUL+sampled activities+arcs for a semantic critique. Author a verdict (anti_steering/in_character/dialogue/arc/mundane 0-5 + flags) thebrief_evidence_checkGATHER profile claims + attached evidence to validate synthesis against reality.brief_persona_revisionGATHER evidence (digests/facts) to propose SLOW identity drift. Change is the exception.cohort_memory_depthHow deep is the cohort's simulated memory (avg facts+events/persona)? A thin cohort should be deepened (simulate-cohort) before a run so councils are evaluate_cohort_diversityStructural bulk-generation gate: flag near-duplicate personas and implausibly uniform cohorts (Jaccard over segment/role/pains/goals/tools). No authorevaluate_simulationRun the quality harness (uniformity, repetition, continuity, project movement, consistency, anti-steering). Returns green/warn/red — the measurable 'tevaluate_simulation_fullCombined 'top' verdict: structural harness + latest LLM critic (definition v2).get_languageRead the active content language (host-authored text) and UI language.get_world_contextThe shared world context (macro facts personas live in) valid at a given date.list_memory_anomaliesFlagged memory anomalies (contradictions / integrity issues), optionally per persona.list_persona_revisionsThe history of evidence-backed identity revisions for a persona.record_cohort_criticPersist the host-authored cohort critique (outliers + cohort_note) as an eval report + an anomaly per flagged outlier persona.record_completeness_criticPersist the independent critic verdict {scores, passed, missing[{kind,what,why, suggested_action}], rationale, evidence_refs}. Honesty gate: cannot berecord_eval_criticPersist the host-authored critic verdict; flags low dimensions + items as anomalies.record_evidence_checkPersist provenance verdict: confirmed/contradicted/unsupported; flags contradictions.record_persona_revisionPersist evidence-backed identity drift (re-renders SOUL); source identity preserved.score_runPersist a RunScore (critic rubric scores + finish + novelty + groundedness + memory depth) so output quality is tracked over time — a regression signaset_languageSet the content language (de|en) for generated text and/or the web UI language. By default content is authored in the language the user writes in; useset_world_contextSet exogenous backdrop facts (season, regulation, market...). Not shared persona knowledge.Ressourcen & Prompts
Resources & prompts3Browsbare Guides und fertige Playbooks.
memory_schemaresource Read-only: the memory object model + the simulate->consolidate->digest loop.research_guideresource THE FRONT DOOR — read this first: the canonical path to drive a research project via MCP.simulate_persona_dayprompt Playbook: drive one persona-day through the full memory loop.