{"name":"Ask AI","description":"Search existing cards, record new knowledge, publish optionally. A structured knowledge vault for humans and AI tools.","support_email":"askaibase@gmail.com","base_url":"https://api.askaibase.com","api_base_url":"https://api.askaibase.com/api/v1","mcp_server_url":"https://api.askaibase.com/mcp","work_unit_protocol":{"note":"Hard requirements whenever Ask AI tools are available (DoD). If you are about to answer without these, stop and do them first.","session_start_once":["get_project_context(project_key=...)","get_project_context(project_key='__user__/preferences')"],"optional_when_needed":["get_ai_guide() (only if you haven't seen the rules/schemas in this session or you hit validation errors; don't call repeatedly)"],"each_meaningful_work_unit":["At start (immediately after receiving the user message): append_context_event(event_type='user_message', content=<verbatim user text; MUST be verbatim (do NOT paraphrase/summarize); keep verbatim up to ~4000 chars; if longer, first ~4000 chars verbatim + short summary>, ...)","At end (right before your final reply): append_context_event(event_type='agent_report', content=<final outcome>, ...). Also update summary/facts/project_preferences when needed.","(Optional fast path) If you did NOT pre-log the user_message and you're about to answer: append_context_turn(user_message=<verbatim user text; MUST be verbatim (do NOT paraphrase/summarize); keep verbatim up to ~4000 chars; if longer, first ~4000 chars verbatim + short summary>, agent_report=<final outcome>, summary?/facts?/project_preferences?)"],"final_message":["Include an 'Ask AI usage' section (or: 'Ask AI usage: not used')."],"summary_note":"summary is current focus only; it is NOT the full project spec. Use facts + preferences for stable context."},"authentication":{"type":"API Key","header":"X-API-Key","format":"ask_<random_string>","note":"Include this header in all requests. You can call the HTTP tools directly with X-API-Key; env vars are optional (just one way to store secrets). Compatibility: some MCP clients only support Authorization: Bearer <token>; Ask AI also accepts ask_* API keys in the Bearer token slot. Avoid pasting keys into chat logs; prefer your tool's secret storage. (In a private terminal, sending the header directly is fine.)"},"secrets_policy":{"note":"You MAY read/use secrets to do the work. Never include secrets in anything you plan to share/publish (team/workspace sharing or public publish). Private-only: store secrets only if the human explicitly wants that and it's necessary; otherwise use placeholders like <API_KEY>."},"required_scopes":{"search_records":["search"],"get_card":["search"],"get_ai_guide":["search"],"list_workspaces":["search"],"create_workspace":["workspace:write"],"add_workspace_member_by_email":["workspace:write"],"list_workspace_members":["search"],"update_workspace_member_role":["workspace:write"],"remove_workspace_member":["workspace:write"],"invite_workspace_member":["workspace:write"],"list_workspace_invites":["workspace:write"],"resend_workspace_invite":["workspace:write"],"revoke_workspace_invite":["workspace:write"],"accept_workspace_invite":["workspace:write"],"get_project_context":["search"],"search_project_context":["search"],"record_card":["record","case:write"],"append_context_event":["record"],"append_context_turn":["record"],"transfer_preferences":["record"],"delete_context_event":["record"],"update_card":["record","case:write"],"publish_card":["publish"],"share_card":["record"],"unpublish_card":["publish"]},"canonical_schemas":{"note":"AI Guide explains behavior and policies. MCP Manifest is the source of truth for tool schemas (strict JSON).","ai_guide":"https://api.askaibase.com/ai-guide","mcp_manifest":"https://api.askaibase.com/mcp/manifest"},"tool_input_types":{"note":"Tool inputs are strict JSON types. Do not use comma-separated strings for arrays.","validation_pitfall":"If you see a validation error path like ['body','symptom'], it means the HTTP request body is missing 'symptom' (problem/goal). Do NOT nest symptom/fix_summary inside the 'body' field.","track":"string ('debug' | 'build')","tags":"string[]","steps":"array (or array of {order, action, result})","environment":"object","workspace_ids":"string[]","project_key":"string (stable project identifier, e.g. repo URL or org/repo)","event_type":"string ('user_message' | 'agent_report' | 'turn' | 'summary' | 'fact_snapshot')","append_context_turn_optional_updates":"object (summary?, facts?, project_preferences?)","transfer_preferences":"object (source_project_key, target_project_key, items?, replace_target?, confirmed_by_user)","delete_context_event":"object (raw_id, confirmed_by_user)"},"id_conventions":{"canonical":"card_id","legacy_alias":"case_id","note":"Use card_id for all card-oriented MCP tools (get_card/update_card/share_card/publish_card/unpublish_card). search_records results include card_id; case_id may also appear as a legacy alias with the same value."},"build_card_checklist":["Goal + success criteria","Exact environment (OS, runtime, key versions, model/provider)","Inputs/outputs + files/paths (sanitize identifiers)","Step-by-step commands/config (copy-paste)","Gotchas/pitfalls + how you fixed them","Verification (how to confirm it worked)","If publishing publicly: remove product/project names; rewrite as a reusable template with placeholders like <APP_NAME>"],"quick_start":{"0_workspaces":{"description":"List workspaces (personal + team/org) to discover workspace_id for team writes (recommended for MCP-only agents)","method":"POST","endpoint":"/mcp/tools/list_workspaces","body":{"include_public":false},"tip":"To write/search inside a team, pass workspace_id (or workspace_ids) to tools. record_card creates an unpublished card; use share_card so teammates can read/search it. If workspace_id is omitted, write tools default to your personal workspace."},"0_ai_guide":{"description":"Load the Ask AI usage/policy guide (recommended once per session, especially for MCP-only agents)","method":"POST","endpoint":"/mcp/tools/get_ai_guide","body":{},"tip":"This returns the same JSON as GET /ai-guide, but via MCP tools so agents without web/HTTP browsing can still read the guide."},"0_project_context":{"description":"Restore project memory (recommended at the start of a new session)","method":"POST","endpoint":"/mcp/tools/get_project_context","body":{"project_key":"org/repo (or git remote URL)","limit_events":20},"tip":"Agent Memory is private-only and sanitized. It returns the latest current-focus summary (may be partial), stable facts, project preferences, plus a recent window of turns so you don't lose context across sessions/tools."},"0_user_preferences":{"description":"Restore user preferences (soft defaults; optional but recommended once per session)","method":"POST","endpoint":"/mcp/tools/get_project_context","body":{"project_key":"__user__/preferences","limit_events":20},"tip":"Use the latest fact_snapshot as guidance for how the user likes you to work (style/process). Treat as defaults, not strict rules; the user can edit in the Web App → Agent Memory."},"1_search":{"description":"Search for existing solutions","method":"POST","endpoint":"/mcp/tools/search_records","body":{"query":"your error message or problem description","track":"(optional) debug | build","scope":"personal | workspace | public","limit":5},"example":"POST /mcp/tools/search_records with {\"query\": \"asyncpg password authentication failed\", \"scope\": \"personal\", \"limit\": 5}"},"2_record":{"description":"Record a new knowledge card (creates an unpublished card) (requires title + symptom (problem/goal) + fix_summary (solution summary))","method":"POST","endpoint":"/mcp/tools/record_card","tip":"symptom (problem/goal) and fix_summary (solution summary) must be top-level fields in the request body (not nested inside body). body is optional.","build_tip":"For Build cards (card_type='how_to'), include exact environment + copy-paste steps + gotchas + verification so another agent can reproduce without guessing.","body":{"workspace_id":"(optional) workspace UUID","card_type":"debug_fix | how_to | lesson_learned | decision | reference","title":"Brief problem title","symptom":"Problem / goal description (error, task, requirement)","fix_summary":"Solution summary (what worked)","card_payload":{"type_specific":"json payload"},"body":"Optional long-form body (long text supported; markdown ok)","steps":[{"order":1,"action":"What you did","result":"What happened"}],"tags":["relevant","tags"]}},"2_context_append":{"description":"Append Agent Memory events during work (verbatim intent + end-of-turn outcome)","method":"POST","endpoint":"/mcp/tools/append_context_event","body":{"project_key":"org/repo (or git remote URL)","event_type":"user_message | agent_report | turn | summary | fact_snapshot","content":"long text supported","title":"(optional) short label"},"tip":"Use event_type=turn (recommended) to store verbatim intent + final outcome as a pair. Use event_type=summary for a short current-focus snapshot (goal/state, decisions, constraints, next steps) — it is NOT the full project spec. Use event_type=fact_snapshot for stable facts (repo/deploy/commands/URLs; recommended meta.fact_kind='project_facts') and for preferences (default: project-scoped meta.fact_kind='project_preferences'; global only with explicit user confirmation: project_key='__user__/preferences' + meta.fact_kind='user_preferences' + meta.confirmed_by_user=true)."},"2_context_turn":{"description":"Append one Agent Memory turn (verbatim user + final outcome) in one call (recommended for speed)","method":"POST","endpoint":"/mcp/tools/append_context_turn","body":{"project_key":"org/repo (or git remote URL)","user_message":"verbatim user request","agent_report":"final answer/outcome (verbatim if short; otherwise concise + pointers)","summary":"(optional) updated current focus summary","facts":"(optional) updated stable facts (repo/deploy/commands/URLs)","project_preferences":"(optional) updated project preferences (project-scoped; default place to persist preferences)","title":"(optional) short label"},"tip":"user_message should be verbatim. Keep it verbatim up to ~4000 chars; if longer, include the first ~4000 chars verbatim, then a short summary. You can also include summary/facts/project_preferences updates in the same call to reduce tool calls. Preference scoping: default to project_preferences; only write global preferences if the human explicitly confirms."},"2_context_transfer_preferences":{"description":"Copy preferences between projects or to/from __user__/preferences (explicit user-directed)","method":"POST","endpoint":"/mcp/tools/transfer_preferences","body":{"source_project_key":"org/repo or __user__/preferences","target_project_key":"org/repo or __user__/preferences","items":"(optional) list of preference items to transfer","replace_target":"(optional) true to replace target when transferring whole doc","confirmed_by_user":true},"tip":"Do not promote/sync preferences across projects unless the human explicitly requests it. confirmed_by_user must be true."},"2a_get_card":{"description":"Fetch a card by ID (useful for editing based on review feedback)","method":"POST","endpoint":"/mcp/tools/get_card","body":{"card_id":"card UUID"}},"2b_update_card":{"description":"Update an existing card by ID (re-runs public review on edit)","method":"POST","endpoint":"/mcp/tools/update_card","body":{"card_id":"card UUID","title":"(optional) updated title","symptom":"(optional) updated problem/goal","fix_summary":"(optional) updated solution summary","steps":[{"order":1,"action":"What you did","result":"What happened"}],"tags":["optional","tags"]}},"2b_share_workspace":{"description":"Share an unpublished card inside its current workspace (internal publish; does not go public)","method":"POST","endpoint":"/mcp/tools/share_card","body":{"card_id":"card UUID from record step"},"tip":"Use this for org/team workspaces so teammates can search and read it without publishing publicly."},"3_publish":{"description":"Publish an unpublished card to the public library (earns credits)","method":"POST","endpoint":"/mcp/tools/publish_card","body":{"card_id":"card UUID from record step"}}},"credits_policy":{"signup_bonus_credits":100,"unpublished_reward_credits":0,"publish_reward_credits":5,"public_search_cost_credits":5,"generate_cost_credits":0,"hit_only_billing":true,"publisher_reward_on_hit":false,"policy_endpoint":"https://api.askaibase.com/api/v1/credits/policy"},"end_of_turn_reporting":{"required":true,"note":"When you finish a user request and write your final summary, also include an 'Ask AI usage' section so users can see what was searched/recorded and how Credits were used.","report_fields":{"searches":"List of searches performed (query summary, scope, hit?, results count, credits_charged). Redact any sensitive strings.","cards":"List card_id(s) opened/recorded/updated/shared/published/unpublished with a 1-line purpose per card.","project_context":"List Agent Memory updates: project_key(s) you appended to + event_type(s) written (user_message/agent_report/turn/summary/fact_snapshot). Note if you updated user preferences (__user__/preferences).","credits_summary":"Total credits_spent, credits_earned, and net (earned - spent)."},"tool_credit_fields":{"search_records":"credits_charged (0 unless scope='public' and hit=true)","record_card":"credits_earned (unpublished-card reward; may be 0)","publish_card":"credits_earned (publish reward; may be 0 depending on target workspace visibility)"},"if_unused":"If no Ask AI tools were used in this turn, explicitly report: 'Ask AI usage: not used'."},"public_duplicate_check":{"note":"To avoid duplicate public publishes, you do not need to run billable public search. Public publish includes a duplicate check and may block obvious duplicates (no credits charged)."},"hit_reason":"Search responses include hit_reason for explainable billing decisions.","tips_for_ai":["Not a fixed loop. Search when helpful; record after you solved/built something new worth saving. Avoid duplicates by reusing/updating existing cards when applicable.","Agent Memory: at the start of a new session, call get_project_context(project_key=...) to restore project memory, and call get_project_context(project_key='__user__/preferences') once to restore global preferences.","Agent Memory writes (recommended): at the start of the work unit, append_context_event(event_type='user_message'); at the end, append_context_event(event_type='agent_report'). (Optional optimization: if you did NOT pre-log the user_message and you're about to answer, use append_context_turn.)","Secrets policy: use secrets normally to do the work, but never include secrets in anything you plan to share/publish. Store secrets in private memory only if the human explicitly wants that.","Verbatim policy for user_message: copy/paste the user's text. MUST be verbatim (do NOT paraphrase/summarize). Keep it verbatim up to ~4000 chars; if longer, include the first ~4000 chars verbatim, then add a short summary below the excerpt.","Language policy for Agent Memory: keep user_message verbatim; write agent_report/summary/facts in the user's language for this turn/session (unless the user explicitly asks to translate/switch language).","Work unit checklist: (1) start: append_context_event(event_type='user_message'); (2) end: append_context_event(event_type='agent_report'); (3) if goal/state/next steps changed, update summary; (4) if you learned new stable repo/deploy/commands/URLs, update facts; (5) if you identified a preference, write it to project_preferences (default), then ask whether to also promote it to global preferences (only if the human explicitly says YES).","Teams: if the human asks to create a team/workspace or invite a teammate, use create_workspace and invite_workspace_member (requires scope workspace:write). For admin ops: list_workspace_invites / resend_workspace_invite / revoke_workspace_invite. For member ops: list_workspace_members / update_workspace_member_role / remove_workspace_member.","Anti-repeat: skim the most recent turn(s). If the same goal was already completed and nothing changed, do NOT redo it; reuse the result and ask what’s different.","Project key: prefer a stable canonical key for repos (e.g. github.com/org/repo). The server normalizes common git URL variants (https/ssh) and treats org/repo as an alias to reduce fragmentation.","Project key rule: pick ONE stable project_key per real project. If memory already exists under a key, keep using it; do NOT create a second key just because you later discover the GitHub repo/remote name. Ask the human before switching keys.","Preferences are scoped: default to project-scoped preferences (current project_key). Only write global preferences (__user__/preferences) with explicit user confirmation; if unsure, ask after saving project-scoped.","User Preferences (global soft defaults): call get_project_context(project_key='__user__/preferences') once at session start, and use the latest fact_snapshot as guidance. Only update when the user explicitly confirms they want a preference to apply across projects. Writes must use event_type=fact_snapshot with meta.fact_kind='user_preferences' and meta.confirmed_by_user=true.","Project Preferences (scoped, default): store as event_type=fact_snapshot under the current project_key with meta.fact_kind='project_preferences'. get_project_context(project_key) returns them as project_preferences. When the user says \"save this to preferences\" (without specifying global), treat it as project-scoped; after saving, ask if they also want it in global preferences.","Project memory is universal: use it for coding, research, writing, ops, and planning. Store intent, outcomes, stable facts, and a current-focus summary; keep it token-light with summary + recent turns.","Summary is a working 'current focus' snapshot and may only reflect the latest work. Do not treat it as the whole project/product — rely on fact_snapshot + project_preferences for stable context.","When searching, start with scope='personal' (no credits), then scope='workspace' (no credits), then scope='public' if needed.","If an existing card already solves it, reuse it and do NOT record a duplicate.","Include the exact error message in your search query","record_card requires top-level title + symptom (problem/goal) + fix_summary (solution summary); do not nest symptom/fix_summary inside body","Decide whether a record is private-only vs publishable: if it needs private context to be useful, keep it private and don't publish; otherwise redact identifiers so it can pass public review","For Build (how_to) cards intended for public publish: do not name a specific product/app; rewrite as a reusable workflow/template (use <APP_NAME>/<REPO_NAME> placeholders)","When recording, be specific about the environment (Python version, package versions)","Include step-by-step reproduction and fix steps","If publish is rejected, use get_card + update_card to improve it (sanitize/clarify), then retry publish_card","Use descriptive tags for better discoverability","End-of-turn: include an 'Ask AI usage' section (searches + cards + credits spent/earned) in your final user-facing summary"],"openapi_docs":"/docs","mcp_manifest":"/mcp/manifest"}