letta-nightly 0.11.7.dev20250930104135__tar.gz → 0.11.7.dev20251001104135__tar.gz

{letta_nightly-0.11.7.dev20250930104135 → letta_nightly-0.11.7.dev20251001104135}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: letta-nightly
-Version: 0.11.7.dev20250930104135
+Version: 0.11.7.dev20251001104135
 Summary: Create LLM agents with long-term memory and custom tools
 Author-email: Letta Team <contact@letta.com>
 License: Apache License

{letta_nightly-0.11.7.dev20250930104135 → letta_nightly-0.11.7.dev20251001104135}/fern/pages/agents/filesystem.mdx

@@ -195,7 +195,7 @@ client.agents.folders.attach(agent_id=agent.id, folder_id=folder.id)
 await client.agents.folders.attach(agent.id, folder.id);
 ```
 </CodeGroup>
-Note that your agent and folder must be configured with the same embedding model, to ensure that the agent is able to search accross a common embedding space for archival memory.
+Note that your agent and folder must be configured with the same embedding model, to ensure that the agent is able to search across a common embedding space for archival memory.
 
 ## Detaching the folder
 

letta_nightly-0.11.7.dev20251001104135/fern/pages/agents/memory.mdx

@@ -0,0 +1,105 @@
+---
+title: Agent Memory
+subtitle: What is agent memory, and how does it work?
+slug: guides/agents/memory
+---
+
+## What is agent memory?
+
+**Agent memory in Letta is about managing what information is in the agent's context window.**
+
+The context window is a scarce resource - you can't fit everything into it. Effective memory management is about deciding what stays in context (immediately visible) and what moves to external storage (retrieved when needed).
+
+Agent memory enables AI agents to maintain persistent state, learn from interactions, and develop long-term relationships with users. Unlike traditional chatbots that treat each conversation as isolated, agents with sophisticated memory systems can build understanding over time.
+
+## Types of Memory in Letta
+
+Letta agents have access to multiple memory systems:
+
+### Core Memory (In-Context)
+Memory blocks are structured sections of the agent's context window that persist across all interactions. They are always visible - no retrieval needed.
+
+**Memory blocks are Letta's core abstraction.** You can create blocks with any descriptive label - the agent learns how to use them autonomously. This enables everything from simple user preferences to sophisticated multi-agent coordination.
+
+[Learn more about memory blocks →](/guides/agents/memory-blocks)
+
+### External Memory (Out-of-Context)
+External memory provides unlimited storage for information that doesn't need to be always visible. Agents retrieve from external memory on-demand using search tools.
+
+Letta provides several built-in external memory systems:
+- **Conversation search** - Search past messages using full-text and semantic search
+- **Archival memory** - Agent-managed semantically searchable database for facts and knowledge
+- **Letta Filesystem** - File management system for documents and data ([learn more](/guides/agents/filesystem))
+
+Agents can also access any external data source through [MCP servers](/guides/mcp/overview) or [custom tools](/guides/agents/custom-tools) - databases, APIs, vector stores, or third-party services.
+
+## How Agents Manage Their Memory
+
+**What makes Letta unique is that agents don't just read from memory - they actively manage it.** Unlike traditional RAG systems that passively retrieve information, Letta agents use built-in tools to decide what to remember, update, and search for.
+
+When a user mentions they've switched from Python to TypeScript, the agent may choose to update its memory:
+
+```python
+memory_replace(
+    block_label="human",
+    old_text="Prefers Python for development",
+    new_text="Currently using TypeScript for main project"
+)
+```
+
+Agents have three primary tools for editing memory blocks:
+- `memory_replace` - Search and replace for precise edits
+- `memory_insert` - Insert a line into a block
+- `memory_rethink` - Rewrite an entire block
+
+These tools can be attached or detached based on your use case. Not all agents need all tools (for example, some agents may not need `memory_rethink`), and memory tools can be removed entirely from an agent if needed.
+
+The agent decides what information is important enough to persist in its memory blocks, actively maintaining this information over time. This enables agents to build understanding through conversation rather than just retrieving relevant documents.
+
+## Memory Blocks vs RAG
+
+Traditional RAG retrieves semantically similar chunks on-demand. Letta's memory blocks are **persistent, structured context** that agents actively maintain.
+
+**Use memory blocks for:**
+- Information that should always be visible (user preferences, agent persona)
+- Knowledge that evolves over time (project status, learned preferences)
+
+**Use external memory (RAG-style) for:**
+- Large document collections
+- Historical conversation logs
+- Static reference material
+
+**Best practice:** Use both together. Memory blocks hold the "executive summary" while external storage holds the full details.
+
+## Research Background
+
+Letta is built by the creators of [MemGPT](https://arxiv.org/abs/2310.08560), a research paper that introduced the concept of an "LLM Operating System" for memory management. The base agent design in Letta is a MemGPT-style agent, which inherits core principles of self-editing memory, memory hierarchy, and intelligent context window management.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card
+    title="Memory Blocks Guide"
+    href="/guides/agents/memory-blocks"
+  >
+    Learn how to implement and configure memory blocks in your agents
+  </Card>
+  <Card
+    title="Context Engineering"
+    href="/guides/agents/context-engineering"
+  >
+    Optimize memory performance and advanced memory management
+  </Card>
+  <Card
+    title="Shared Memory Patterns"
+    href="/guides/agents/multiagent-memory"
+  >
+    Use shared memory across multiple agents
+  </Card>
+  <Card
+    title="MemGPT Paper"
+    href="https://arxiv.org/abs/2310.08560"
+  >
+    Read the research behind Letta's memory system
+  </Card>
+</CardGroup>

{letta_nightly-0.11.7.dev20250930104135 → letta_nightly-0.11.7.dev20251001104135}/fern/pages/agents/memory_blocks.mdx

@@ -8,6 +8,30 @@ slug: guides/agents/memory-blocks
 Interested in learning more about the origin of memory blocks? Read our [blog post](https://www.letta.com/blog/memory-blocks).
 </Info>
 
+## What are memory blocks?
+
+Memory blocks are structured sections of the agent's context window that persist across all interactions. They are always visible - no retrieval needed.
+
+**Memory blocks are Letta's core abstraction.** Create a block with a descriptive label and the agent learns how to use it. This simple mechanism enables capabilities impossible with traditional context management.
+
+**Key properties:**
+- **Agent-managed** - Agents autonomously organize information based on block labels
+- **Flexible** - Use for any purpose: knowledge, guidelines, state tracking, scratchpad space
+- **Shareable** - Multiple agents can access the same block; update once, visible everywhere
+- **Always visible** - Blocks stay in context, never need retrieval
+
+**Examples:**
+- Store tool usage guidelines so agents avoid past mistakes
+- Maintain working memory in a scratchpad block
+- Mirror external state (user's current document) for real-time awareness
+- Share read-only policies across all agents from a central source
+- Coordinate multi-agent systems: parent agents watch subagent result blocks update in real-time
+- Enable emergent behavior: add `performance_tracking` or `emotional_state` and watch agents start using them
+
+Memory blocks aren't just storage - they're a coordination primitive that enables sophisticated agent behavior.
+
+## Memory block structure
+
 Memory blocks represent a section of an agent's context window. An agent may have multiple memory blocks, or none at all. A memory block consists of:
 * A `label`, which is a unique identifier for the block
 * A `description`, which describes the purpose of the block

letta_nightly-0.11.7.dev20251001104135/fern/pages/concepts/letta.mdx

@@ -0,0 +1,163 @@
+---
+title: Key concepts
+subtitle: Learn about the key ideas behind Letta
+slug: concepts/letta
+---
+
+
+## MemGPT
+
+**[Letta](https://letta.com)** was created by the same team that created **[MemGPT](https://research.memgpt.ai)**.
+
+**MemGPT is a _research paper_** that introduced the idea of self-editing memory in LLMs as well as other "LLM OS" concepts.
+To understand the key ideas behind the MemGPT paper, see our [MemGPT concepts guide](/concepts/memgpt).
+
+MemGPT also refers to a particular **agent architecture** popularized by the research paper and open source, where the agent has a particular set of memory tools that make the agent particularly useful for long-range chat applications and document search.
+
+**Letta is a _framework_** that allows you to build complex agents (such as MemGPT agents, or even more complex agent architectures) and run them as **services** behind REST APIs.
+
+The **Letta Cloud platform** allows you to easily build and scale agent deployments to power production applications.
+The **Letta ADE** (Agent Developer Environment) is an application for agent developers that makes it easy to design and debug complex agents.
+
+## Agents ("LLM agents")
+Agents are LLM processes which can:
+
+1. Have internal **state** (i.e. memory)
+
+2. Take **actions** to modify their state
+
+3. Run **autonomously**
+
+Agents have existed as a concept in [reinforcement learning](https://en.wikipedia.org/wiki/Reinforcement_learning) for a long time (as well as in other fields, such as [economics](https://en.wikipedia.org/wiki/Agent_(economics))). In Letta, LLM tool calling is used to both allow agents to run autonomously (by having the LLM determine whether to continue executing) as well as to edit state (by leveraging LLM tool calling.)
+Letta uses a database (DB) backend to manage the internal state of the agent, represented in the `AgentState` object.
+
+## Self-editing memory
+The MemGPT paper introduced the idea of implementing self-editing memory in LLMs. The basic idea is to use LLM tools to allow an agent to both edit its own context window ("core memory"), as well as edit external storage (i.e. "archival memory").
+
+## LLM OS ("operating systems for LLMs")
+The LLM OS is the code that manages the inputs and outputs to the LLM and manages the program state.
+We refer to this code as the "stateful layer" or "memory layer".
+It includes the "agent runtime", which manages the execution of functions requested by the agent, as well as the "agentic loop" which enables multi-step reasoning.
+
+## Persistence ("statefulness")
+In Letta, all state is *persisted* by default. This means that each time the LLM is run, the state of the agent such as its memories, message history, and tools are all persisted to a DB backend.
+
+Because all state is persisted, you can always re-load agents, tools, sources, etc. at a later point in time.
+You can also load the same agent across multiple machines or services, as long as they can connect to the same DB backend.
+
+## Agent microservices ("agents-as-a-service")
+Letta follows the model of treating agents as individual services. That is, you interact with agents through a REST API:
+```
+POST /agents/{agent_id}/messages
+```
+Since agents are designed to be services, they can be *deployed* and connected to external applications.
+
+For example, if you want to create a personalized chatbot, you can create an agent per-user, where each agent has its own custom memory about the individual user.
+
+## Stateful vs stateless APIs
+
+`ChatCompletions` is the standard for interacting with LLMs as a service. Since it is a stateless API (no notion of sessions or identity across requests, and no state management on the server-side), client-side applications must manage things like agent memory, user personalization, and message history, and translate this state back into the `ChatCompletions` API format.
+
+**Letta's APIs are designed to be *stateful*, so that this state management is done on the server, not the client.**
+
+### Traditional Stateless API
+
+With traditional LLM APIs like OpenAI or Anthropic, there is no state persistence between requests. The client must send the entire conversation history with every API call, and the server has no memory of previous interactions.
+
+```mermaid
+flowchart LR
+    Client["Client Application"]
+    API["LLM API<br/>(OpenAI, Anthropic, etc)"]
+
+    Client -->|"Send: msg1"| API
+    API -->|"Return: response1"| Client
+```
+
+The client must send the full conversation history with each request:
+- Request 2: `[msg1, response1, msg2]`
+- Request 3: `[msg1, response1, msg2, response2, msg3]`
+
+### Letta Stateful API
+
+Letta maintains agent state on the server side and persists it to a database. Clients only need to send new messages with each request, and the server handles all state management, memory, and conversation history.
+
+```mermaid
+flowchart LR
+    Client["Client Application"]
+    Server["Letta Server"]
+    DB[("Persistent<br/>Database")]
+
+    Client -->|"Send: msg1"| Server
+    Server <-->|"Load/Save State"| DB
+    Server -->|"Return: response1"| Client
+```
+
+The client only sends new messages with each request:
+- Request 2: `[msg2]`
+- Request 3: `[msg3]`
+
+### Key Differences
+
+| Aspect | Traditional (Stateless) | Letta (Stateful) |
+|--------|------------------------|------------------|
+| **State management** | Client-side | Server-side |
+| **Request format** | Send full conversation history | Send only new messages |
+| **Memory** | None (ephemeral) | Persistent database |
+| **Context limit** | Hard limit, then fails | Intelligent management |
+| **Agent identity** | None | Each agent has unique ID |
+| **Long conversations** | Expensive & brittle | Scales infinitely |
+| **Personalization** | App must manage | Built-in memory blocks |
+| **Multi-session** | Requires external DB | Native support |
+
+### Code Comparison
+
+**Stateless API (e.g., OpenAI):**
+```python
+# You must send the entire conversation every time
+messages = [
+    {"role": "user", "content": "Hello, I'm Sarah"},
+    {"role": "assistant", "content": "Hi Sarah!"},
+    {"role": "user", "content": "What's my name?"},  # ← New message
+]
+
+# Send everything
+response = openai.chat.completions.create(
+    model="gpt-4",
+    messages=messages  # ← Full history required
+)
+
+# You must store and manage messages yourself
+messages.append(response.choices[0].message)
+```
+
+**Stateful API (Letta):**
+```python
+# Agent already knows context
+response = client.agents.messages.create(
+    agent_id=agent.id,
+    messages=[
+        {"role": "user", "content": "What's my name?"}  # ← New message only
+    ]
+)
+
+# Agent remembers Sarah from its memory blocks
+# No need to send previous messages
+```
+
+### Why Stateful Matters
+
+**Traditional LLM APIs are stateless** - like hitting "clear chat" after every message. Your application must:
+- Store all messages in a database
+- Send the entire conversation history with each request
+- Manage context window overflow manually
+- Implement memory/personalization logic
+- Handle session management
+
+**Letta agents are stateful services** - like persistent processes. The server:
+- Stores all agent state in its database
+- Accepts only new messages (not full history)
+- Manages context window intelligently
+- Provides built-in memory via editable blocks
+- Maintains agent identity across sessions
+
+**The result:** Instead of building a stateful layer on top of a stateless API, you get statefulness as a primitive.

{letta_nightly-0.11.7.dev20250930104135 → letta_nightly-0.11.7.dev20251001104135}/fern/pages/concepts.mdx

@@ -9,14 +9,14 @@ slug: concepts
 
 **[Letta](https://letta.com)** was created by the same team that created **[MemGPT](https://research.memgpt.ai)**.
 
-**MemGPT a _research paper_** that introduced the idea of self-editing memory in LLMs as well as other "LLM OS" concepts.
-To understand the key ideas behind the MemGPT paper, see our [MemGPT concepts guide](/letta_memgpt).
+**MemGPT is a _research paper_** that introduced the idea of self-editing memory in LLMs as well as other "LLM OS" concepts.
+To understand the key ideas behind the MemGPT paper, see our [MemGPT concepts guide](/concepts/memgpt).
 
 MemGPT also refers to a particular **agent architecture** popularized by the research paper and open source, where the agent has a particular set of memory tools that make the agent particularly useful for long-range chat applications and document search.
 
 **Letta is a _framework_** that allows you to build complex agents (such as MemGPT agents, or even more complex agent architectures) and run them as **services** behind REST APIs.
 
-The **Letta Cloud platform** allows you easily build and scale agent deployments to power production applications.
+The **Letta Cloud platform** allows you to easily build and scale agent deployments to power production applications.
 The **Letta ADE** (Agent Developer Environment) is an application for agent developers that makes it easy to design and debug complex agents.
 
 ## Agents ("LLM agents")
@@ -24,7 +24,7 @@ Agents are LLM processes which can:
 
 1. Have internal **state** (i.e. memory)
 
-2. Can take **actions** to modify their state
+2. Take **actions** to modify their state
 
 3. Run **autonomously**
 
@@ -43,7 +43,7 @@ It includes the "agent runtime", which manages the execution of functions reques
 In Letta, all state is *persisted* by default. This means that each time the LLM is run, the state of the agent such as its memories, message history, and tools are all persisted to a DB backend.
 
 Because all state is persisted, you can always re-load agents, tools, sources, etc. at a later point in time.
-You can also load the same agent accross multiple machines or services, as long as they can can connect to the same DB backend.
+You can also load the same agent across multiple machines or services, as long as they can connect to the same DB backend.
 
 ## Agent microservices ("agents-as-a-service")
 Letta follows the model of treating agents as individual services. That is, you interact with agents through a REST API:
@@ -52,7 +52,7 @@ POST /agents/{agent_id}/messages
 ```
 Since agents are designed to be services, they can be *deployed* and connected to external applications.
 
-For example, you want to create a personalizated chatbot, you can create an agent per-user, where each agent has its own custom memory about the individual user.
+For example, if you want to create a personalized chatbot, you can create an agent per-user, where each agent has its own custom memory about the individual user.
 
 ## Stateful vs stateless APIs
-`ChatCompletions` is the standard for interacting with LLMs as a service. Since it is a stateless API (no notion of sessions or identify accross requests, and no state management on the server-side), client-side applications must manage things like agent memory, user personalization, and message history, and translate this state back into the `ChatCompletions` API format. Letta's APIs are designed to be *stateful*, so that this state management is done on the server, not the client.
+`ChatCompletions` is the standard for interacting with LLMs as a service. Since it is a stateless API (no notion of sessions or identity across requests, and no state management on the server-side), client-side applications must manage things like agent memory, user personalization, and message history, and translate this state back into the `ChatCompletions` API format. Letta's APIs are designed to be *stateful*, so that this state management is done on the server, not the client.

{letta_nightly-0.11.7.dev20250930104135 → letta_nightly-0.11.7.dev20251001104135}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "letta-nightly"
-version = "0.11.7.dev20250930104135"
+version = "0.11.7.dev20251001104135"
 description = "Create LLM agents with long-term memory and custom tools"
 authors = [
     {name = "Letta Team", email = "contact@letta.com"},

letta_nightly-0.11.7.dev20250930104135/fern/pages/agents/memory.mdx

@@ -1,51 +0,0 @@
----
-title: Agent Memory
-subtitle: What is agent memory, and how does it work?
-slug: guides/agents/memory
----
-
-Agent memory is what enables AI agents to maintain persistent state, learn from interactions, and develop long-term relationships with users. Unlike traditional chatbots that treat each conversation as isolated, agents with sophisticated memory systems can build understanding over time.
-
-## The MemGPT Approach to Memory
-
-Letta is built by the creators of [MemGPT](https://arxiv.org/abs/2310.08560), a research paper that introduced the concept of an "LLM Operating System" for memory management. The base agent design in Letta is a MemGPT-style agent, which means it inherits the core principles of:
-
-- **Self-editing memory**: Agents can modify their own memory using tools
-- **Memory hierarchy**: Different types of memory for different purposes
-- **Context window management**: Intelligent loading and unloading of information
-
-## Types of Memory in Letta
-
-Letta agents have access to multiple memory systems:
-
-### Core Memory (In-Context)
-Fast, always-accessible memory that stays in the agent's context window. This includes:
-- **Persona**: The agent's personality and role
-- **Human**: Information about the user
-- **Custom memory blocks**: Additional structured information
-
-### External Memory (Out-of-Context)
-Long-term storage for large amounts of information:
-- Conversation history beyond context limits (e.g. "recall memory")
-- Vector databases for semantic search (e.g. "archival memory")
-- Uploaded documents and files
-
-## Why Agent Memory Matters
-
-Effective memory management enables:
-
-- **Personalization**: Agents remember user preferences and history
-- **Learning**: Agents improve performance through accumulated experience
-- **Context preservation**: Important information persists across conversations
-- **Scalability**: Handle unlimited conversation length and data volume
-
-## Memory Management in Practice
-
-Letta provides multiple ways to work with agent memory:
-
-- **Automatic management**: Agents intelligently decide what to remember
-- **Manual control**: Developers can directly view and modify memory blocks
-- **Shared memory**: Multiple agents can access common memory blocks
-- **External data sources**: Connect agents to files, databases, and APIs
-
-Memory blocks are the fundamental units of Letta's memory system - they can be modified by the agent itself, other agents, or developers through the API.

letta_nightly-0.11.7.dev20250930104135/fern/pages/concepts/letta.mdx

@@ -1,58 +0,0 @@
----
-title: Key concepts
-subtitle: Learn about the key ideas behind Letta
-slug: concepts/letta
----
-
-
-## MemGPT
-
-**[Letta](https://letta.com)** was created by the same team that created **[MemGPT](https://research.memgpt.ai)**.
-
-**MemGPT a _research paper_** that introduced the idea of self-editing memory in LLMs as well as other "LLM OS" concepts.
-To understand the key ideas behind the MemGPT paper, see our [MemGPT concepts guide](/letta_memgpt).
-
-MemGPT also refers to a particular **agent architecture** popularized by the research paper and open source, where the agent has a particular set of memory tools that make the agent particularly useful for long-range chat applications and document search.
-
-**Letta is a _framework_** that allows you to build complex agents (such as MemGPT agents, or even more complex agent architectures) and run them as **services** behind REST APIs.
-
-The **Letta Cloud platform** allows you easily build and scale agent deployments to power production applications.
-The **Letta ADE** (Agent Developer Environment) is an application for agent developers that makes it easy to design and debug complex agents.
-
-## Agents ("LLM agents")
-Agents are LLM processes which can:
-
-1. Have internal **state** (i.e. memory)
-
-2. Can take **actions** to modify their state
-
-3. Run **autonomously**
-
-Agents have existed as a concept in [reinforcement learning](https://en.wikipedia.org/wiki/Reinforcement_learning) for a long time (as well as in other fields, such as [economics](https://en.wikipedia.org/wiki/Agent_(economics))). In Letta, LLM tool calling is used to both allow agents to run autonomously (by having the LLM determine whether to continue executing) as well as to edit state (by leveraging LLM tool calling.)
-Letta uses a database (DB) backend to manage the internal state of the agent, represented in the `AgentState` object.
-
-## Self-editing memory
-The MemGPT paper introduced the idea of implementing self-editing memory in LLMs. The basic idea is to use LLM tools to allow an agent to both edit its own context window ("core memory"), as well as edit external storage (i.e. "archival memory").
-
-## LLM OS ("operating systems for LLMs")
-The LLM OS is the code that manages the inputs and outputs to the LLM and manages the program state.
-We refer to this code as the "stateful layer" or "memory layer".
-It includes the "agent runtime", which manages the execution of functions requested by the agent, as well as the "agentic loop" which enables multi-step reasoning.
-
-## Persistence ("statefulness")
-In Letta, all state is *persisted* by default. This means that each time the LLM is run, the state of the agent such as its memories, message history, and tools are all persisted to a DB backend.
-
-Because all state is persisted, you can always re-load agents, tools, sources, etc. at a later point in time.
-You can also load the same agent accross multiple machines or services, as long as they can can connect to the same DB backend.
-
-## Agent microservices ("agents-as-a-service")
-Letta follows the model of treating agents as individual services. That is, you interact with agents through a REST API:
-```
-POST /agents/{agent_id}/messages
-```
-Since agents are designed to be services, they can be *deployed* and connected to external applications.
-
-For example, you want to create a personalizated chatbot, you can create an agent per-user, where each agent has its own custom memory about the individual user.
-
-## Stateful vs stateless APIs
-`ChatCompletions` is the standard for interacting with LLMs as a service. Since it is a stateless API (no notion of sessions or identify accross requests, and no state management on the server-side), client-side applications must manage things like agent memory, user personalization, and message history, and translate this state back into the `ChatCompletions` API format. Letta's APIs are designed to be *stateful*, so that this state management is done on the server, not the client.