mantle-tools-and-memory
Write Rasa Mantle tools (Python) and design memory scoping. Use when adding a tool, when a tool isn't discovered, when deciding local vs shared tools, or when choosing project memory vs skill memory.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 44
- Forks
- 19
01 前言 Front Matter
- name
- mantle-tools-and-memory
- description
- Write Rasa Mantle tools (Python) and design memory scoping. Use when adding a tool, when a tool isn't discovered, when deciding local vs shared tools, or when choosing project memory vs skill memory.
03 SKILL.md 正文
Tools and memory — the scoping model
The two scopes, one sentence each
- Project memory (
memory.yml, repo root): facts that outlive a single skill — identity, preferences, session state. Every skill reads and writes it. Tool-written only:llm_settable: truehere is rejected by the engine at validate time. - Skill memory (
skills/<id>/memory.yml): one skill's working state, underschema: public:. This is wherellm_settable: trueis allowed.
Rule of thumb: if a later skill could skip work because of it (customer id, authenticated flag, chosen language) → project memory, set by a tool. If it only matters until this skill finishes (which account they asked about) → skill memory, settable by the LLM.
Writing a tool
Always import from the project's shim, never from rasa.* directly:
"""LOCAL tool for check_balance — reading a balance is this skill's job alone."""
from __future__ import annotations
from lib.engine import ToolContext, ToolResult, tool
@tool(description="Return the balance of one of the signed-in customer's accounts.")
async def fetch_balance(account_number: str, context: ToolContext = None) -> ToolResult:
"""Look up a single account balance.
Args:
account_number: The account number to read.
"""
customer_id = context.memory.get("project.customer_id") if context else None
if not customer_id:
return ToolResult(llm_response={"ok": False, "error": "not_authenticated"})
account = lookup(customer_id, account_number)
if account is None:
return ToolResult(llm_response={"ok": False, "error": "account_not_found"})
if context is not None:
context.memory.set("account_number", account_number) # skill scope
return ToolResult(llm_response={
"ok": True, "account_number": account_number,
"balance": account.balance, "currency": "GBP",
})
The load-bearing facts:
- Discovery is by the
_tool_descriptionattribute the@tooldecorator sets — where you import the decorator from makes no difference, which is why thelib/engine.pyshim is safe. - Tools are
async def, take typed args pluscontext: ToolContext = None, and returnToolResult(llm_response={...}). context.memory.get("project.<field>")reads project memory;context.memory.set("<field>", value)writes this skill's scope.- Return structured dicts with an
ok/errorshape, never prose. Error values like"not_authenticated"become branch points in skill prose ("If it returnsnot_authenticated, tell the caller you need to verify them first"). Include recovery data on errors (e.g.known_accounts).
Local vs shared
skills/<id>/tools.py— tools only that skill uses. No registration needed.tools/(project root) — tools used by 2+ skills; each consuming skill lists them underimport_tools:in its frontmatter. Document the choice in the docstring ("shared with other skills, so it is imported rather than living in this skill's folder").
Authority pattern (the one worth copying everywhere)
Make ONE tool the authority for each invariant, and let skills defer to it:
the balance tool checks authentication itself by reading
project.customer_id, so no skill can leak a balance by forgetting a check —
the prose then says the tool "is the authority on whether the caller is
verified." Guardrails in tools are enforced; guardrails only in prose are
requests.
Verify
python3 scripts/lint_mantle.py --check project-memory-writesmake validate(engine-level: rejects rootllm_settable, missing tools, bad constraints)
04 同仓库更多 Skills
Build a travel desk
Handle developer requests to build or extend a Mantle travel agent using four approved travel tools.
Travel briefing
Answer questions about flight status, tonight’s departures, airport weather and currency conversion.
Review Dispute
Ask the outside reviewer about a card dispute, then block the card if the caller confirms. Activate when the caller reports a card transaction they did not make.
Block Card
Block a customer's lost or stolen card. Activate when the caller wants a card blocked.
Block Card
Block a customer's lost or stolen card. Activate when the caller wants a card blocked.
Block Card
Block a customer's lost or stolen card. Activate when the caller wants a card blocked.