letta_api

Letta is the platform for building stateful agents: open AI with advanced memory that can learn and self-improve over time.

https://github.com/letta-ai/letta

Keywords

ai ai-agents llm llm-agent

Keywords from Contributors

agents mlops langchain gemini anthropic multi-agents rag vector-database web-crawler pydantic

Last synced: 6 months ago · JSON representation ·

Repository

Letta is the platform for building stateful agents: open AI with advanced memory that can learn and self-improve over time.

Basic Info

Host: GitHub
Owner: letta-ai
License: apache-2.0
Language: Python
Default Branch: main
Homepage: https://docs.letta.com/
Size: 45.2 MB

Statistics

Stars: 18,199
Watchers: 136
Forks: 1,895
Open Issues: 71
Releases: 162

Topics

ai ai-agents llm llm-agent

Created over 2 years ago · Last pushed 6 months ago

Metadata Files

Readme Contributing License Citation

Letta (formerly MemGPT)

Letta is the platform for building stateful agents: open AI with advanced memory that can learn and self-improve over time.

Quicklinks:

Developer Documentation: Learn how create agents that learn using Python / TypeScript
Agent Development Environment (ADE): A no-code UI for building stateful agents
Letta Desktop: A fully-local version of the ADE, available on MacOS and Windows
Letta Cloud: The fastest way to try Letta, with agents running in the cloud

Get started

To get started, install the Letta SDK (available for both Python and TypeScript):

Simple Hello World example

In the example below, we'll create a stateful agent with two memory blocks, one for itself (the persona block), and one for the human. We'll initialize the human memory block with incorrect information, and correct agent in our first message - which will trigger the agent to update its own memory with a tool call.

To run the examples, you'll need to get a LETTA_API_KEY from Letta Cloud, or run your own self-hosted server (see our guide)

Python

```python from letta_client import Letta

client = Letta(token="LETTAAPIKEY")

client = Letta(baseurl="http://localhost:8283") # if self-hosting, set your baseurl

agentstate = client.agents.create( model="openai/gpt-4.1", embedding="openai/text-embedding-3-small", memoryblocks=[ { "label": "human", "value": "The human's name is Chad. They like vibe coding." }, { "label": "persona", "value": "My name is Sam, a helpful assistant." } ], tools=["websearch", "runcode"] )

print(agent_state.id)

agent-d9be...0846

response = client.agents.messages.create( agentid=agentstate.id, messages=[ { "role": "user", "content": "Hey, nice to meet you, my name is Brad." } ] )

the agent will think, then edit its memory using a tool

for message in response.messages: print(message) ```

TypeScript / Node.js

```typescript import { LettaClient } from '@letta-ai/letta-client'

const client = new LettaClient({ token: "LETTAAPIKEY" }); // const client = new LettaClient({ baseUrl: "http://localhost:8283" }); // if self-hosting, set your baseUrl

const agentState = await client.agents.create({ model: "openai/gpt-4.1", embedding: "openai/text-embedding-3-small", memoryBlocks: [ { label: "human", value: "The human's name is Chad. They like vibe coding." }, { label: "persona", value: "My name is Sam, a helpful assistant." } ], tools: ["websearch", "runcode"] });

console.log(agentState.id); // agent-d9be...0846

const response = await client.agents.messages.create( agentState.id, { messages: [ { role: "user", content: "Hey, nice to meet you, my name is Brad." } ] } );

// the agent will think, then edit its memory using a tool for (const message of response.messages) { console.log(message); } ```

Core concepts in Letta:

Letta is made by the creators of MemGPT, a research paper that introduced the concept of the "LLM Operating System" for memory management. The core concepts in Letta for designing stateful agents follow the MemGPT LLM OS principles:

Memory Hierarchy: Agents have self-editing memory that is split between in-context memory and out-of-context memory
Memory Blocks: The agent's in-context memory is composed of persistent editable memory blocks
Agentic Context Engineering: Agents control the context window by using tools to edit, delete, or search for memory
Perpetual Self-Improving Agents: Every "agent" is a single entity that has a perpetual (infinite) message history

Multi-agent shared memory (full guide)

A single memory block can be attached to multiple agents, allowing to extremely powerful multi-agent shared memory setups. For example, you can create two agents that have their own independent memory blocks in addition to a shared memory block.

Python

```python

create a shared memory block

shared_block = client.blocks.create( label="organization", description="Shared information between all agents within the organization.", value="Nothing here yet, we should update this over time." )

create a supervisor agent

supervisoragent = client.agents.create( model="anthropic/claude-3-5-sonnet-20241022", embedding="openai/text-embedding-3-small", # blocks created for this agent memoryblocks=[{"label": "persona", "value": "I am a supervisor"}], # pre-existing shared block that is "attached" to this agent blockids=[sharedblock.id], )

create a worker agent

workeragent = client.agents.create( model="openai/gpt-4.1-mini", embedding="openai/text-embedding-3-small", # blocks created for this agent memoryblocks=[{"label": "persona", "value": "I am a worker"}], # pre-existing shared block that is "attached" to this agent blockids=[sharedblock.id], ) ```

TypeScript / Node.js

```typescript // create a shared memory block const sharedBlock = await client.blocks.create({ label: "organization", description: "Shared information between all agents within the organization.", value: "Nothing here yet, we should update this over time." });

// create a supervisor agent const supervisorAgent = await client.agents.create({ model: "anthropic/claude-3-5-sonnet-20241022", embedding: "openai/text-embedding-3-small", // blocks created for this agent memoryBlocks: [{ label: "persona", value: "I am a supervisor" }], // pre-existing shared block that is "attached" to this agent blockIds: [sharedBlock.id] });

// create a worker agent const workerAgent = await client.agents.create({ model: "openai/gpt-4.1-mini", embedding: "openai/text-embedding-3-small", // blocks created for this agent memoryBlocks: [{ label: "persona", value: "I am a worker" }], // pre-existing shared block that is "attached" to this agent blockIds: [sharedBlock.id] }); ```

Sleep-time agents (full guide)

In Letta, you can create special sleep-time agents that share the memory of your primary agents, but run in the background (like an agent's "subconcious"). You can think of sleep-time agents as a special form of multi-agent architecture.

To enable sleep-time agents for your agent, set the enable_sleeptime flag to true when creating your agent. This will automatically create a sleep-time agent in addition to your main agent which will handle the memory editing, instead of your primary agent.

Python

python agent_state = client.agents.create( ... enable_sleeptime=True, # <- enable this flag to create a sleep-time agent )

TypeScript / Node.js

typescript const agentState = await client.agents.create({ ... enableSleeptime: true // <- enable this flag to create a sleep-time agent });

Saving and sharing agents with Agent File (`.af`) (full guide)

In Letta, all agent data is persisted to disk (Postgres or SQLite), and can be easily imported and exported using the open source Agent File (.af) file format. You can use Agent File to checkpoint your agents, as well as move your agents (and their complete state/memories) between different Letta servers, e.g. between self-hosted Letta and Letta Cloud.

View code snippets

### Python ```python # Import your .af file from any location agent_state = client.agents.import_agent_serialized(file=open("/path/to/agent/file.af", "rb")) print(f"Imported agent: {agent.id}") # Export your agent into a serialized schema object (which you can write to a file) schema = client.agents.export_agent_serialized(agent_id="") ``` ### TypeScript / Node.js ```typescript import { readFileSync } from 'fs'; import { Blob } from 'buffer'; // Import your .af file from any location const file = new Blob([readFileSync('/path/to/agent/file.af')]) const agentState = await client.agents.importAgentSerialized(file, {}) console.log(`Imported agent: ${agentState.id}`); // Export your agent into a serialized schema object (which you can write to a file) const schema = await client.agents.exportAgentSerialized(""); ```

Model Context Protocol (MCP) and custom tools (full guide)

Letta has rich support for MCP tools (Letta acts as an MCP client), as well as custom Python tools. MCP servers can be easily added within the Agent Development Environment (ADE) tool manager UI, as well as via the SDK:

View code snippets

### Python ```python # List tools from an MCP server tools = client.tools.list_mcp_tools_by_server(mcp_server_name="weather-server") # Add a specific tool from the MCP server tool = client.tools.add_mcp_tool( mcp_server_name="weather-server", mcp_tool_name="get_weather" ) # Create agent with MCP tool attached agent_state = client.agents.create( model="openai/gpt-4o-mini", embedding="openai/text-embedding-3-small", tool_ids=[tool.id] ) # Or attach tools to an existing agent client.agents.tool.attach( agent_id=agent_state.id tool_id=tool.id ) # Use the agent with MCP tools response = client.agents.messages.create( agent_id=agent_state.id, messages=[ { "role": "user", "content": "Use the weather tool to check the forecast" } ] ) ``` ### TypeScript / Node.js ```typescript // List tools from an MCP server const tools = await client.tools.listMcpToolsByServer("weather-server"); // Add a specific tool from the MCP server const tool = await client.tools.addMcpTool("weather-server", "get_weather"); // Create agent with MCP tool const agentState = await client.agents.create({ model: "openai/gpt-4o-mini", embedding: "openai/text-embedding-3-small", toolIds: [tool.id] }); // Use the agent with MCP tools const response = await client.agents.messages.create(agentState.id, { messages: [ { role: "user", content: "Use the weather tool to check the forecast" } ] }); ```

Filesystem (full guide)

Letta’s filesystem allow you to easily connect your agents to external files, for example: research papers, reports, medical records, or any other data in common text formats (.pdf, .txt, .md, .json, etc). Once you attach a folder to an agent, the agent will be able to use filesystem tools (open_file, grep_file, search_file) to browse the files to search for information.

View code snippets

### Python ```python # get an available embedding_config embedding_configs = client.embedding_models.list() embedding_config = embedding_configs[0] # create the folder folder = client.folders.create( name="my_folder", embedding_config=embedding_config ) # upload a file into the folder job = client.folders.files.upload( folder_id=folder.id, file=open("my_file.txt", "rb") ) # wait until the job is completed while True: job = client.jobs.retrieve(job.id) if job.status == "completed": break elif job.status == "failed": raise ValueError(f"Job failed: {job.metadata}") print(f"Job status: {job.status}") time.sleep(1) # once you attach a folder to an agent, the agent can see all files in it client.agents.folders.attach(agent_id=agent.id, folder_id=folder.id) response = client.agents.messages.create( agent_id=agent_state.id, messages=[ { "role": "user", "content": "What data is inside of my_file.txt?" } ] ) for message in response.messages: print(message) ``` ### TypeScript / Node.js ```typescript // get an available embedding_config const embeddingConfigs = await client.embeddingModels.list() const embeddingConfig = embeddingConfigs[0]; // create the folder const folder = await client.folders.create({ name: "my_folder", embeddingConfig: embeddingConfig }); // upload a file into the folder const uploadJob = await client.folders.files.upload( createReadStream("my_file.txt"), folder.id, ); console.log("file uploaded") // wait until the job is completed while (true) { const job = await client.jobs.retrieve(uploadJob.id); if (job.status === "completed") { break; } else if (job.status === "failed") { throw new Error(`Job failed: ${job.metadata}`); } console.log(`Job status: ${job.status}`); await new Promise((resolve) => setTimeout(resolve, 1000)); } // list files in the folder const files = await client.folders.files.list(folder.id); console.log(`Files in folder: ${files}`); // list passages in the folder const passages = await client.folders.passages.list(folder.id); console.log(`Passages in folder: ${passages}`); // once you attach a folder to an agent, the agent can see all files in it await client.agents.folders.attach(agent.id, folder.id); const response = await client.agents.messages.create( agentState.id, { messages: [ { role: "user", content: "What data is inside of my_file.txt?" } ] } ); for (const message of response.messages) { console.log(message); } ```

Long-running agents (full guide)

When agents need to execute multiple tool calls or perform complex operations (like deep research, data analysis, or multi-step workflows), processing time can vary significantly. Letta supports both a background mode (with resumable streaming) as well as an async mode (with polling) to enable robust long-running agent executions.

View code snippets

### Python ```python stream = client.agents.messages.create_stream( agent_id=agent_state.id, messages=[ { "role": "user", "content": "Run comprehensive analysis on this dataset" } ], stream_tokens=True, background=True, ) run_id = None last_seq_id = None for chunk in stream: if hasattr(chunk, "run_id") and hasattr(chunk, "seq_id"): run_id = chunk.run_id # Save this to reconnect if your connection drops last_seq_id = chunk.seq_id # Save this as your resumption point for cursor-based pagination print(chunk) # If disconnected, resume from last received seq_id: for chunk in client.runs.stream(run_id, starting_after=last_seq_id): print(chunk) ``` ### TypeScript / Node.js ```typescript const stream = await client.agents.messages.createStream({ agentId: agentState.id, requestBody: { messages: [ { role: "user", content: "Run comprehensive analysis on this dataset" } ], streamTokens: true, background: true, } }); let runId = null; let lastSeqId = null; for await (const chunk of stream) { if (chunk.run_id && chunk.seq_id) { runId = chunk.run_id; // Save this to reconnect if your connection drops lastSeqId = chunk.seq_id; // Save this as your resumption point for cursor-based pagination } console.log(chunk); } // If disconnected, resume from last received seq_id for await (const chunk of client.runs.stream(runId, {startingAfter: lastSeqId})) { console.log(chunk); } ```

Using local models

Letta is model agnostic and supports using local model providers such as Ollama and LM Studio. You can also easily swap models inside an agent after the agent has been created, by modifying the agent state with the new model provider via the SDK or in the ADE.

Development (only needed if you need to modify the server code)

Note: this repostory contains the source code for the core Letta service (API server), not the client SDKs. The client SDKs can be found here: Python, TypeScript.

To install the Letta server from source, fork the repo, clone your fork, then use uv to install from inside the main directory: sh cd letta uv sync --all-extras

To run the Letta server from source, use uv run: sh uv run letta server

Contributing

Letta is an open source project built by over a hundred contributors. There are many ways to get involved in the Letta OSS project!

Join the Discord: Chat with the Letta devs and other AI developers.
Chat on our forum: If you're not into Discord, check out our developer forum.
Follow our socials: Twitter/X, LinkedIn, YouTube

**Legal notices: By using Letta and related Letta services (such as the Letta endpoint or hosted service), you are agreeing to our privacy policy and terms of service.

Owner

Name: letta-ai
Login: letta-ai
Kind: organization

Repositories: 1
Profile: https://github.com/letta-ai

Citation (CITATION.cff)

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
title: "Letta"
url: "https://github.com/letta-ai/letta"
preferred-citation:
  type: article
  authors:
  - family-names: "Packer"
    given-names: "Charles"
  - family-names: "Wooders"
    given-names: "Sarah"
  - family-names: "Lin"
    given-names: "Kevin"
  - family-names: "Fang"
    given-names: "Vivian"
  - family-names: "Patil"
    given-names: "Shishir G"
  - family-names: "Stoica"
    given-names: "Ion"
  - family-names: "Gonzalez"
    given-names: "Joseph E"
  journal: "arXiv preprint arXiv:2310.08560"
  month: 10
  title: "MemGPT: Towards LLMs as Operating Systems"
  year: 2023

Committers

Last synced: 10 months ago

All Time

Total Commits: 2,453
Total Committers: 134
Avg Commits per committer: 18.306
Development Distribution Score (DDS): 0.724

Past Year

Commits: 1,428
Committers: 70
Avg Commits per committer: 20.4
Development Distribution Score (DDS): 0.756

Top Committers

Name	Email	Commits
Charles Packer	p**s@g**m	677
Sarah Wooders	s**s@g**m	527
Matthew Zhou	m**4@g**m	349
cthomas	c**n@l**m	290
Vivian Fang	hi@v****h	143
Shubham Naik	s**0@g**m	57
Robin Goetz	3****n	28
Kevin Lin	k**1@g**m	26
mlong93	3****3	25
Matt Zhou	m**u@M**l	25
Kian Jones	k**n@l**m	19
Andy Li	5****y	17
tombedor	t**r@g**m	15
Shubham Naik	s**b@m**i	10
Will Sargent	w**t@g**m	10
madgrizzle	j**n@t**e	9
lemorage	o**e@g**m	9
Shishir Patil	s**l@b**u	8
Krishnakumar R (KK)	6****c	7
Maximilian Winter	m**1@g**m	7
Max Blackmer	m**x@a**s	7
RT	r**r@a**m	7
Qingzheng Gao	g**h@g**m	6
jnjpng	j**n@l**m	5
Adam	s**j@g**m	5
Hans Raaf	h**a@o**e	5
Ethan Knox	e**n@k**v	4
Stephan Fitzpatrick	s**n@k**m	4
Ikko Eltociear Ashimine	e**r@g**m	4
Jim Lloyd	j**d@g**m	4
and 104 more...

Committer Domains (Top 20 + Academic)

letta.com: 4 berkeley.edu: 2 vivi.sh: 1 memgpt.ai: 1 thehogans.name: 1 agiletechnologist.us: 1 atlanticdynamic.com: 1 oderwat.de: 1 knox.dev: 1 knowsuchagency.com: 1 qq.com: 1 tevinzhang.com: 1 claudiocambra.com: 1 biltrewards.com: 1 ella-lab.io: 1 pm.me: 1 live.cn: 1 vysona.com: 1 fsu.edu: 1 wlabel.co: 1 ischool.berkeley.edu: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 497
Total pull requests: 996
Average time to close issues: 5 months
Average time to close pull requests: 5 days
Total issue authors: 256
Total pull request authors: 74
Average comments per issue: 2.18
Average comments per pull request: 0.46
Merged pull requests: 757
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 247
Pull requests: 985
Average time to close issues: about 1 month
Average time to close pull requests: 3 days
Issue authors: 162
Pull request authors: 69
Average comments per issue: 1.89
Average comments per pull request: 0.43
Merged pull requests: 757
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

cpacker (40)
sarahwooders (32)
lemorage (17)
raolak (15)
quantumalchemy (13)
goetzrobin (12)
jimlloyd (9)
agiletechnologist (8)
wsargent (8)
stevenbaert (7)
distributev (7)
scenaristeur (7)
jfkirk (6)
Sapessii (5)
a67793581 (5)

Pull Request Authors

sarahwooders (280)
mattzh72 (142)
cpacker (136)
carenthomas (129)
4shub (34)
wsargent (29)
lemorage (23)
kianjones9 (22)
mlong93 (19)
kk-src (16)
kl2806 (12)
fredzolio (8)
andrewrfitz (8)
khangich (6)
cliandy (6)

Top Labels

Issue Labels

auto-closed (250) stale (80) bug (30) enhancement (19) feature request (17) good first issue (16) help wanted (14) priority (13) API (9) ChatUI (4) portal (4) roadmap (4) testing (3) local-llm (2) autogen (2) azure (1) documentation (1) invalid (1)

Pull Request Labels

safe to test (9) auto-closed (9) merge-hold (2) documentation (1) help wanted (1) good first issue (1) API (1) portal (1)

Packages

Total packages: 1
Total downloads:
- hex 41 total

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 1
Total maintainers: 1

hex.pm: letta_api

Elixir client library for the Letta AI API, providing comprehensive access to AI agent functionality including memory management, conversation handling, and tool integration.

Homepage: https://hexdocs.pm/letta_api
Documentation: http://hexdocs.pm/letta_api/
License: MIT
Latest release: 1.0.0
published 8 months ago

Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 41 Total

Rankings

Forks count: 0.0%

Stargazers count: 0.0%

Average: 12.7%

Dependent packages count: 19.3%

Dependent repos count: 31.5%

Maintainers (1)

mark.antoine

Last synced: 6 months ago

letta_api

Science Score: 64.0%

Keywords

Keywords from Contributors

Basic Info

Statistics

Topics

Metadata Files

Letta (formerly MemGPT)

Quicklinks:

Get started

Simple Hello World example

Python

client = Letta(baseurl="http://localhost:8283") # if self-hosting, set your baseurl

agent-d9be...0846

the agent will think, then edit its memory using a tool

TypeScript / Node.js

Core concepts in Letta:

Multi-agent shared memory (full guide)

Python

create a shared memory block

create a supervisor agent

create a worker agent

TypeScript / Node.js

Sleep-time agents (full guide)

Python

TypeScript / Node.js

Saving and sharing agents with Agent File (.af) (full guide)

Model Context Protocol (MCP) and custom tools (full guide)

Filesystem (full guide)

Long-running agents (full guide)

Using local models

Development (only needed if you need to modify the server code)

Contributing

Citation (CITATION.cff)

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

hex.pm: letta_api

Rankings

Maintainers (1)

Dependencies

Saving and sharing agents with Agent File (`.af`) (full guide)