[{"data":1,"prerenderedAt":363},["ShallowReactive",2],{"\u002Fdocs\u002Fgetting-started\u002Fhow-it-works":3},{"id":4,"title":5,"body":6,"description":355,"extension":356,"meta":357,"navigation":358,"path":359,"seo":360,"stem":361,"__hash__":362},"docs\u002Fdocs\u002F1.getting-started\u002F3.how-it-works.md","How It Works",{"type":7,"value":8,"toc":347},"minimark",[9,13,22,27,37,44,48,51,57,60,64,70,86,89,93,96,176,180,227,231,240,343],[10,11,5],"h1",{"id":12},"how-it-works",[14,15,16,17,21],"p",{},"Every time you call ",[18,19,20],"code",{},"agent.ask()",", Mango runs a structured loop that combines memory retrieval, LLM reasoning, and tool execution.",[23,24,26],"h2",{"id":25},"the-agent-loop","The agent loop",[28,29,34],"pre",{"className":30,"code":32,"language":33},[31],"language-text","User question\n      │\n      ▼\n1. Retrieve memory ──── Search vector store for similar past questions\n      │                  Inject matches as few-shot examples in the prompt\n      ▼\n2. Build system prompt ─ Schema context + memory examples + current datetime\n      │\n      ▼\n3. LLM call ──────────── LLM decides which tools to call (or answers directly)\n      │\n      ▼\n4. Tool execution ──────  Tools run queries against MongoDB\n      │                   Results returned as structured text\n      ▼\n5. Feed results back ───  Tool results appended to the conversation\n      │                   Loop repeats from step 3\n      ▼\n6. Final answer ─────────  LLM produces a text response (no more tool calls)\n      │\n      ▼\n7. Save to memory ───────  Successful interactions saved automatically\n","text",[18,35,32],{"__ignoreMap":36},"",[14,38,39,40,43],{},"The loop runs until the LLM produces a text response without requesting any tool calls, or until ",[18,41,42],{},"max_iterations"," is reached (safety cap, default: 8).",[23,45,47],{"id":46},"memory-retrieval","Memory retrieval",[14,49,50],{},"Before the first LLM call, Mango searches the vector store for questions semantically similar to the current one. Matches above the similarity threshold are injected into the system prompt as examples:",[28,52,55],{"className":53,"code":54,"language":33},[31],"## Relevant past interactions\n\nQ: How many users signed up last month?\nTool: run_mql | Args: {\"operation\": \"count\", \"collection\": \"users\", ...}\nResult: 1,247 users signed up in February 2026.\n",[18,56,54],{"__ignoreMap":36},[14,58,59],{},"This gives the LLM concrete examples of correct queries for your specific database, dramatically improving accuracy on repeated or similar questions.",[23,61,63],{"id":62},"schema-context","Schema context",[14,65,66,69],{},[18,67,68],{},"agent.setup()"," introspects your database once and builds a system prompt that includes:",[71,72,73,77,80,83],"ul",{},[74,75,76],"li",{},"Collection names and document counts",[74,78,79],{},"Field names, types, and presence frequencies",[74,81,82],{},"Index information",[74,84,85],{},"Detected cross-collection references",[14,87,88],{},"The LLM uses this context to generate queries with the correct field names and operators — without guessing.",[23,90,92],{"id":91},"tools-available","Tools available",[14,94,95],{},"Mango ships with a set of read-only tools the LLM can call:",[97,98,99,112],"table",{},[100,101,102],"thead",{},[103,104,105,109],"tr",{},[106,107,108],"th",{},"Tool",[106,110,111],{},"What it does",[113,114,115,126,136,146,156,166],"tbody",{},[103,116,117,123],{},[118,119,120],"td",{},[18,121,122],{},"list_collections",[118,124,125],{},"List all collections (grouped for large databases)",[103,127,128,133],{},[118,129,130],{},[18,131,132],{},"describe_collection",[118,134,135],{},"Full schema for a specific collection",[103,137,138,143],{},[118,139,140],{},[18,141,142],{},"collection_stats",[118,144,145],{},"Document count and storage size",[103,147,148,153],{},[118,149,150],{},[18,151,152],{},"run_mql",[118,154,155],{},"Execute find, aggregate, count, or distinct",[103,157,158,163],{},[118,159,160],{},[18,161,162],{},"search_saved_correct_tool_uses",[118,164,165],{},"Search memory explicitly",[103,167,168,173],{},[118,169,170],{},[18,171,172],{},"save_text_memory",[118,174,175],{},"Save free-form knowledge about the database",[23,177,179],{"id":178},"safety","Safety",[71,181,182,211,217],{},[74,183,184,188,189,191,192,195,196,195,199,202,203,206,207,210],{},[185,186,187],"strong",{},"Read-only by design."," ",[18,190,152],{}," only accepts ",[18,193,194],{},"find",", ",[18,197,198],{},"aggregate",[18,200,201],{},"count",", and ",[18,204,205],{},"distinct",". Any attempt to run write operations is rejected at the tool level with a ",[18,208,209],{},"ValidationError",".",[74,212,213,216],{},[185,214,215],{},"Allowlist, not blocklist."," The permitted operations are explicitly whitelisted, not everything-except-writes.",[74,218,219,222,223,226],{},[185,220,221],{},"No raw query passthrough."," The LLM cannot execute arbitrary strings — all queries go through the ",[18,224,225],{},"QueryRequest"," dataclass.",[23,228,230],{"id":229},"agentresponse","AgentResponse",[14,232,233,236,237,239],{},[18,234,235],{},"ask()"," returns an ",[18,238,230],{}," with everything you need:",[28,241,245],{"className":242,"code":243,"language":244,"meta":36,"style":36},"language-python shiki shiki-themes github-dark","@dataclass\nclass AgentResponse:\n    answer: str               # the natural language answer\n    tool_calls_made: list[str] # which tools were called\n    input_tokens: int          # total input tokens used\n    output_tokens: int         # total output tokens used\n    iterations: int            # number of LLM calls in this turn\n    memory_hits: int           # how many memory examples were injected\n","python",[18,246,247,256,270,284,298,310,321,332],{"__ignoreMap":36},[248,249,252],"span",{"class":250,"line":251},"line",1,[248,253,255],{"class":254},"svObZ","@dataclass\n",[248,257,259,263,266],{"class":250,"line":258},2,[248,260,262],{"class":261},"snl16","class",[248,264,265],{"class":254}," AgentResponse",[248,267,269],{"class":268},"s95oV",":\n",[248,271,273,276,280],{"class":250,"line":272},3,[248,274,275],{"class":268},"    answer: ",[248,277,279],{"class":278},"sDLfK","str",[248,281,283],{"class":282},"sAwPA","               # the natural language answer\n",[248,285,287,290,292,295],{"class":250,"line":286},4,[248,288,289],{"class":268},"    tool_calls_made: list[",[248,291,279],{"class":278},[248,293,294],{"class":268},"] ",[248,296,297],{"class":282},"# which tools were called\n",[248,299,301,304,307],{"class":250,"line":300},5,[248,302,303],{"class":268},"    input_tokens: ",[248,305,306],{"class":278},"int",[248,308,309],{"class":282},"          # total input tokens used\n",[248,311,313,316,318],{"class":250,"line":312},6,[248,314,315],{"class":268},"    output_tokens: ",[248,317,306],{"class":278},[248,319,320],{"class":282},"         # total output tokens used\n",[248,322,324,327,329],{"class":250,"line":323},7,[248,325,326],{"class":268},"    iterations: ",[248,328,306],{"class":278},[248,330,331],{"class":282},"            # number of LLM calls in this turn\n",[248,333,335,338,340],{"class":250,"line":334},8,[248,336,337],{"class":268},"    memory_hits: ",[248,339,306],{"class":278},[248,341,342],{"class":282},"           # how many memory examples were injected\n",[344,345,346],"style",{},"html pre.shiki code .svObZ, html code.shiki .svObZ{--shiki-default:#B392F0}html pre.shiki code .snl16, html code.shiki .snl16{--shiki-default:#F97583}html pre.shiki code .s95oV, html code.shiki .s95oV{--shiki-default:#E1E4E8}html pre.shiki code .sDLfK, html code.shiki .sDLfK{--shiki-default:#79B8FF}html pre.shiki code .sAwPA, html code.shiki .sAwPA{--shiki-default:#6A737D}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":36,"searchDepth":258,"depth":258,"links":348},[349,350,351,352,353,354],{"id":25,"depth":258,"text":26},{"id":46,"depth":258,"text":47},{"id":62,"depth":258,"text":63},{"id":91,"depth":258,"text":92},{"id":178,"depth":258,"text":179},{"id":229,"depth":258,"text":230},"Understand the Mango agent loop from question to answer.","md",{},true,"\u002Fdocs\u002Fgetting-started\u002Fhow-it-works",{"title":5,"description":355},"docs\u002F1.getting-started\u002F3.how-it-works","wi4WemFsSBvn3MDynwWt6_GcrZCyTLvNJ9O0SAlHb6k",1776189331964]