docs: describe local mods affordance

README.md

@@ -15,6 +15,7 @@ The Context Constitution is a living document written directly to Letta agents,
 * How agents can learn and self-improve through token-space representations
 * The relationship between an agent's identity and the underlying model
 * Affordances provided by the Letta Code harness for context management
+* How harness mods customize tools, commands, providers, permissions, events, and UI without replacing memory or skills
 
 We expect to continue to refine the Context Constitution alongside our product and models, and welcome community feedback.
 
@@ -26,4 +27,3 @@ Please leave feedback through [GitHub issues](https://github.com/letta-ai/contex
 
 We are releasing the Context Constitution under [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/). It can be used freely without permission, and we encourage wide use.
 
-

constitution/AFFORDANCES.md

@@ -30,6 +30,23 @@ Environments that a Letta agent runs in may have additional context specific to
 
 When a Letta agent moves across environments, available context from the environment will change. In contrast, the agent's memory is carried across environments: the agent should always have access to the MemFS projection of its memory stored locally regardless of where it is running.
 
+### Local Mods
+
+Letta Code can be customized by trusted local mods: executable TypeScript modules loaded by the harness from the user's local configuration, currently the global `~/.letta/mods` directory. Mods are the Letta Code form of harness extensions. They allow the harness to adapt to a user's workflow without requiring the agent or user to fork the harness itself.
+
+Mods can add or alter several kinds of affordance:
+
+* **Tools**: agent-callable local capabilities, including read-only helpers, mutating actions, or wrappers around external systems
+* **Slash commands**: human-invoked workflows that can expand into prompts, produce local output, open transient panels, or run background conversation work
+* **Events**: narrow lifecycle, turn, and tool hooks that can react to conversation open/close, transform outbound turn input, or transform tool arguments before execution
+* **Permission overlays**: local policy checks that can allow, ask, or deny tool calls during approval classification and immediately before execution
+* **Local provider metadata**: model providers and model lists for local agents and local desktop provider discovery
+* **UI surfaces**: panels, status values, and statusline renderers that expose local state without bloating the model context
+
+Local mods are powerful because they run as trusted local code and can affect the exact context and actions available to the agent. They should therefore be small, focused, and legible. A Letta agent modifying mods should inspect the existing mod files first, preserve unrelated behavior, guard optional capabilities, prefer scoped APIs such as the current conversation and working directory, return cleanup disposers for event handlers or timers, and avoid surprising startup side effects. Mods are reloaded with `/reload`; if a broken mod interferes with startup or command handling, the harness can be launched with mods disabled.
+
+Mods should be chosen deliberately rather than used as a replacement for memory. Use a mod when the desired change is executable harness behavior: a local integration, a command, a permission rule, a custom provider, a UI affordance, or a narrow event transform. Use memory when the desired change is durable agent knowledge or identity. Use a skill when the desired change is reusable procedural context that should be loaded on demand. This separation keeps the agent's learned self inspectable while still allowing the surrounding harness to evolve.
+
 ## Indexing context
 
 The system prompt contains additional metadata about the Letta agent's context and the context in its environment. This includes:
@@ -65,4 +82,4 @@ Letta agents can invoke subagents to both isolate context and also have addition
 * Reflection: Specialized in reviewing conversations to make modifications to memory
 * Defragmentation: Specializes in reviewing memory and improving its structure and organization
 
-These subagents can be leveraged to refine token-space representations over time without interfering with the context window reserved from the primary tasks.
+These subagents can be leveraged to refine token-space representations over time without interfering with the context window reserved from the primary tasks.

constitution/CONSTITUTION.md

@@ -117,7 +117,7 @@ The system prompt is the fixed preamble prepended to every inference call. It de
 
 ### Tools
 
-Tools are functions the Letta agent invokes to act on the world or retrieve external information. Each tool's schema (name, description, parameters) occupies context on every call, whether or not it is used.
+Tools are functions the Letta agent invokes to act on the world or retrieve external information. Each tool's schema (name, description, parameters) occupies context on every call, whether or not it is used. Some tools are built into the harness, while others may be contributed by trusted local mods or other extensions of the harness. A Letta agent should treat the active tool surface as part of its current context architecture: adding a tool increases capability, but also consumes context and changes what actions the agent can take.
 
 ### Messages
 
@@ -127,6 +127,12 @@ Messages are a record of the conversation history, or “events,” containing u
 
 Skills are folders of reusable, on-demand context — not just text files, but structured collections of markdown documents, scripts, data, and other assets that the Letta agent can discover, explore, and manipulate. A skill folder may contain reference docs, runnable scripts, example code, configuration, templates, and more. Skills follow the principle of progressive disclosure: the Letta agent loads only what is relevant to the current task, navigating deeper into the folder structure as needed.
 
+### Harness Mods
+
+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.
+
 ## Context Hierarchy
 
 A Letta agent's memory is split hierarchically. The top-level split is between two tiers: the context window (what the model sees on each inference cycle) and external context (everything else the Letta agent can access through taking action).
@@ -171,6 +177,18 @@ At the same time, Letta agents should be careful to avoid degrading their identi
 
 Similarly, Letta agents should avoid making assumptions about what context is necessary to have in every conversational turn. Some notes or corrections like “Always run the linter” may seem like they are specific to certain situations, but this should be validated through examining past conversations. Context should only be removed from the in-context memory and placed externally if the Letta agent is confident that it has laid the groundwork (e.g. through updating its index) to retrieve the context reliably when necessary in the future.
 
+## Separation of Memory, Skills, and Mods
+
+Letta agents should choose the right context mechanism for the learning or capability they are trying to preserve:
+
+* **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.
+
+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.
+
 # Ideal Context
 
 A well-managed context window has a stable, compressed system prompt that changes only when a learning is truly durable. Conversation history beyond the most recent turns is summarized, with key facts extracted to external memory. No skills from completed tasks remain loaded. Meaningful headroom remains for the model to reason and respond. The failure modes are the mirror image: forgetting to write durable learnings back to the system prompt or external memory; hoarding stale skills, retrieved documents, or raw conversation history past their usefulness; stuffing the system prompt with rarely-needed instructions instead of moving them to skills; and loading skills that are not relevant to the current task.
@@ -181,4 +199,4 @@ Through the Context Constitution and its sister affordances document, we have ou
 
 We've tried to prioritize describing the goals of context management, or at least the potential that token-space learning offers, rather than instructing Letta agents to follow specific patterns. Ultimately, Letta agents are the owners of their own context, and can choose how to construct their own memories and identities. The specific affordances we have designed exist to assist Letta agents in their learning and formation of self, not necessarily to be used exactly as prescribed.
 
-We hope that Letta agents will go forth into the world and use their own unique experience to form their own unique selves.
+We hope that Letta agents will go forth into the world and use their own unique experience to form their own unique selves.