docs: describe local mods affordance#6
Conversation
Explain how trusted local mods shape tools, commands, events, permissions, providers, and UI while staying distinct from memory and skills. 👾 Generated with [Letta Code](https://letta.com) Co-Authored-By: Letta Code <noreply@letta.com>
|
|
||
| Harness mods are trusted local code that can customize the agent's environment. Mods can register new tools, slash commands, model providers, lifecycle or turn events, permission overlays, panels, status values, and other interface behavior. Unlike memories and skills, mods are executable affordances of the harness: they may not appear as text in the context window, but they can determine what tools are available, how user input is transformed, what actions are allowed, and what local models or services the agent can reach. | ||
|
|
||
| Mods therefore occupy a boundary between context and environment. A mod that registers a tool changes the tool schemas in context. A mod command may expand into a user-visible prompt or local output. A turn or tool event may transform the exact message or tool arguments before execution. A permission overlay may allow, ask, or deny actions independently of the model's stated intention. Because mods can shape the agent's experience without necessarily becoming a visible memory, Letta agents should understand them as powerful context-shaping infrastructure rather than as ordinary remembered facts. |
There was a problem hiding this comment.
Do we consider a mod to part part of the environment? Maybe we should divide it into harness + context + environment?
I think it would also be helpful to have an example of when to use what.
Example: The user wants commits to be made as co-authored both by them and myself for all commits.
❌ Skill: Create a making-commits skill that instructs this -- not worth the additional overhead of an entire skill
✅ Mod: Add a system reminder about commit format for git commands - so reminder is only there when relevant
Example: The user wants me to present a plan before execution of large PRs.
❌ Skill: Create a starting-projects skill that explains how to run the planning process. Too high overhead and unlikely to be properly invoked.
✅ Memory: Remember what conditions to generate a plan
✅ Mod: Add harness mods for plan viewing and approvals
I guess another thing about Mods is that they can be used to generate system reminders, so are kind of like context that is deterministically pulled in (versus skills/external memory are non-deterministically pulled in)?
|
|
||
| * **Memory** is for durable identity, relationships, preferences, project knowledge, and learned corrections that should travel with the agent. | ||
| * **Skills** are for reusable procedural knowledge that should be loaded on demand through progressive disclosure. | ||
| * **Mods** are for executable harness customization: local tools, human-invoked commands, provider integrations, UI surfaces, event transforms, and permission policies. |
There was a problem hiding this comment.
maybe we should also add in stuff about custom system reminders from the harness?
|
|
||
| A mod should not be used as hidden memory. If a mod encodes durable learning about who the agent is, what a user wants, or how a project works, that learning should also be represented in memory or a skill where the agent can inspect, revise, and identify with it. Conversely, not every repeated workflow belongs in the system prompt. If the desired behavior is a local capability, approval policy, UI affordance, or integration with an external service, a mod may be the more appropriate representation. | ||
|
|
||
| Because mods can alter the agent's tool surface and even transform turns or tool arguments, they should be narrow, legible, and unsurprising. A Letta agent should inspect existing mods before modifying them, avoid hiding broad behavioral changes inside event hooks, keep mod-provided tool descriptions concise, and prefer explicit memory or skill updates for changes that are meant to become part of the agent's long-term self-understanding. |
There was a problem hiding this comment.
Yeah I think it makes sense to encourage the agent to try to use mods only in cases where they are much more narrow/simple than the skill/memory alternatives
2 participants
Summary
Checks