Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: Add block history tables (#1489)
Matthew Zhouaa05df68a770
diff --git a/alembic/versions/bff040379479_add_block_history_tables.py b/alembic/versions/bff040379479_add_block_history_tables.pynew file mode 100644index 000000000..80c6cb331--- /dev/null+++ b/alembic/versions/bff040379479_add_block_history_tables.py@@ -0,0 +1,65 @@+"""Add block history tables++Revision ID: bff040379479+Revises: a66510f83fc2+Create Date: 2025-03-31 14:49:30.449052++"""++from typing import Sequence, Union++import sqlalchemy as sa++from alembic import op++# revision identifiers, used by Alembic.+revision: str = "bff040379479"+down_revision: Union[str, None] = "a66510f83fc2"+branch_labels: Union[str, Sequence[str], None] = None+depends_on: Union[str, Sequence[str], None] = None+++def upgrade() -> None:+ # ### commands auto generated by Alembic - please adjust! ###+ op.create_table(+ "block_history",+ sa.Column("description", sa.Text(), nullable=True),+ sa.Column("label", sa.String(), nullable=False),+ sa.Column("value", sa.Text(), nullable=False),+ sa.Column("limit", sa.BigInteger(), nullable=False),+ sa.Column("metadata_", sa.JSON(), nullable=True),+ sa.Column("actor_type", sa.String(), nullable=True),+ sa.Column("actor_id", sa.String(), nullable=True),+ sa.Column("block_id", sa.String(), nullable=False),+ sa.Column("sequence_number", sa.Integer(), nullable=False),+ sa.Column("organization_id", sa.String(), nullable=False),+ sa.Column("id", sa.String(), nullable=False),+ sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=True),+ sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=True),+ sa.Column("is_deleted", sa.Boolean(), server_default=sa.text("FALSE"), nullable=False),+ sa.Column("_created_by_id", sa.String(), nullable=True),+ sa.Column("_last_updated_by_id", sa.String(), nullable=True),+ sa.ForeignKeyConstraint(["block_id"], ["block.id"], ondelete="CASCADE"),+ sa.ForeignKeyConstraint(+ ["organization_id"],+ ["organizations.id"],+ ),+ sa.PrimaryKeyConstraint("id"),+ )+ op.create_index("ix_block_history_block_id_sequence", "block_history", ["block_id", "sequence_number"], unique=True)+ op.add_column("block", sa.Column("current_history_entry_id", sa.String(), nullable=True))+ op.add_column("block", sa.Column("version", sa.Integer(), server_default="1", nullable=False))+ op.create_index(op.f("ix_block_current_history_entry_id"), "block", ["current_history_entry_id"], unique=False)+ op.create_foreign_key("fk_block_current_history_entry", "block", "block_history", ["current_history_entry_id"], ["id"], use_alter=True)+ # ### end Alembic commands ###+++def downgrade() -> None:+ # ### commands auto generated by Alembic - please adjust! ###+ op.drop_constraint("fk_block_current_history_entry", "block", type_="foreignkey")+ op.drop_index(op.f("ix_block_current_history_entry_id"), table_name="block")+ op.drop_column("block", "version")+ op.drop_column("block", "current_history_entry_id")+ op.drop_index("ix_block_history_block_id_sequence", table_name="block_history")+ op.drop_table("block_history")+ # ### end Alembic commands ###diff --git a/letta/orm/__init__.py b/letta/orm/__init__.pyindex a43f6e0bc..0dad525c0 100644--- a/letta/orm/__init__.py+++ b/letta/orm/__init__.py@@ -2,6 +2,7 @@ from letta.orm.agent import Agentfrom letta.orm.agents_tags import AgentsTagsfrom letta.orm.base import Basefrom letta.orm.block import Block+from letta.orm.block_history import BlockHistoryfrom letta.orm.blocks_agents import BlocksAgentsfrom letta.orm.file import FileMetadatafrom letta.orm.group import Groupdiff --git a/letta/orm/block.py b/letta/orm/block.pyindex 940a8ec9e..edd56d0c0 100644--- a/letta/orm/block.py+++ b/letta/orm/block.py@@ -1,9 +1,10 @@from typing import TYPE_CHECKING, List, Optional, Type-from sqlalchemy import JSON, BigInteger, Index, Integer, UniqueConstraint, event-from sqlalchemy.orm import Mapped, attributes, mapped_column, relationship+from sqlalchemy import JSON, BigInteger, ForeignKey, Index, Integer, String, UniqueConstraint, event+from sqlalchemy.orm import Mapped, attributes, declared_attr, mapped_column, relationshipfrom letta.constants import CORE_MEMORY_BLOCK_CHAR_LIMIT+from letta.orm.block_history import BlockHistoryfrom letta.orm.blocks_agents import BlocksAgentsfrom letta.orm.mixins import OrganizationMixinfrom letta.orm.sqlalchemy_base import SqlalchemyBase@@ -38,6 +39,17 @@ class Block(OrganizationMixin, SqlalchemyBase):limit: Mapped[BigInteger] = mapped_column(Integer, default=CORE_MEMORY_BLOCK_CHAR_LIMIT, doc="Character limit of the block.")metadata_: Mapped[Optional[dict]] = mapped_column(JSON, default={}, doc="arbitrary information related to the block.")+ # history pointers / locking mechanisms+ current_history_entry_id: Mapped[Optional[str]] = mapped_column(+ String, ForeignKey("block_history.id", name="fk_block_current_history_entry", use_alter=True), nullable=True, index=True+ )+ version: Mapped[int] = mapped_column(+ Integer, nullable=False, default=1, server_default="1", doc="Optimistic locking version counter, incremented on each state change."+ )+ # NOTE: This takes advantage of built-in optimistic locking functionality by SqlAlchemy+ # https://docs.sqlalchemy.org/en/20/orm/versioning.html+ __mapper_args__ = {"version_id_col": version}+# relationshipsorganization: Mapped[Optional["Organization"]] = relationship("Organization")agents: Mapped[List["Agent"]] = relationship(@@ -68,6 +80,17 @@ class Block(OrganizationMixin, SqlalchemyBase):model_dict["metadata"] = self.metadata_return Schema.model_validate(model_dict)+ @declared_attr+ def current_history_entry(cls) -> Mapped[Optional["BlockHistory"]]:+ # Relationship to easily load the specific history entry that is current+ return relationship(+ "BlockHistory",+ primaryjoin=lambda: cls.current_history_entry_id == BlockHistory.id,+ foreign_keys=[cls.current_history_entry_id],+ lazy="joined", # Typically want current history details readily available+ post_update=True,+ ) # Helps manage potential FK cycles+@event.listens_for(Block, "after_update") # Changed from 'before_update'def block_before_update(mapper, connection, target):diff --git a/letta/orm/block_history.py b/letta/orm/block_history.pynew file mode 100644index 000000000..de1b0c5dd--- /dev/null+++ b/letta/orm/block_history.py@@ -0,0 +1,46 @@+import uuid+from typing import Optional++from sqlalchemy import JSON, BigInteger, ForeignKey, Index, Integer, String, Text+from sqlalchemy.orm import Mapped, mapped_column++from letta.orm.enums import ActorType+from letta.orm.mixins import OrganizationMixin+from letta.orm.sqlalchemy_base import SqlalchemyBase+++class BlockHistory(OrganizationMixin, SqlalchemyBase):+ """Stores a single historical state of a Block for undo/redo functionality."""++ __tablename__ = "block_history"++ __table_args__ = (+ # PRIMARY lookup index for finding specific history entries & ordering+ Index("ix_block_history_block_id_sequence", "block_id", "sequence_number", unique=True),+ )++ # agent generates its own id+ # TODO: We want to migrate all the ORM models to do this, so we will need to move this to the SqlalchemyBase+ # TODO: Some still rely on the Pydantic object to do this+ id: Mapped[str] = mapped_column(String, primary_key=True, default=lambda: f"block_hist-{uuid.uuid4()}")++ # Snapshot State Fields (Copied from Block)+ description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)+ label: Mapped[str] = mapped_column(String, nullable=False)+ value: Mapped[str] = mapped_column(Text, nullable=False)+ limit: Mapped[BigInteger] = mapped_column(BigInteger, nullable=False)+ metadata_: Mapped[Optional[dict]] = mapped_column(JSON, nullable=True)++ # Editor info+ # These are not made to be FKs because these may not always exist (e.g. a User be deleted after they made a checkpoint)+ actor_type: Mapped[Optional[ActorType]] = mapped_column(String, nullable=True)+ actor_id: Mapped[Optional[str]] = mapped_column(String, nullable=True)++ # Relationships+ block_id: Mapped[str] = mapped_column(+ String, ForeignKey("block.id", ondelete="CASCADE"), nullable=False # History deleted if Block is deleted+ )++ sequence_number: Mapped[int] = mapped_column(+ Integer, nullable=False, doc="Monotonically increasing sequence number for the history of a specific block_id, starting from 1."+ )diff --git a/letta/orm/enums.py b/letta/orm/enums.pyindex 9f0141621..5bf0648ce 100644--- a/letta/orm/enums.py+++ b/letta/orm/enums.py@@ -22,3 +22,9 @@ class ToolSourceType(str, Enum):python = "python"json = "json"+++class ActorType(str, Enum):+ LETTA_USER = "letta_user"+ LETTA_AGENT = "letta_agent"+ LETTA_SYSTEM = "letta_system"diff --git a/letta/orm/sqlalchemy_base.py b/letta/orm/sqlalchemy_base.pyindex 85ccfd850..8a06b1c60 100644--- a/letta/orm/sqlalchemy_base.py+++ b/letta/orm/sqlalchemy_base.py@@ -370,17 +370,19 @@ class SqlalchemyBase(CommonSqlalchemyMetaMixins, Base):return []@handle_db_timeout- def create(self, db_session: "Session", actor: Optional["User"] = None) -> "SqlalchemyBase":+ def create(self, db_session: "Session", actor: Optional["User"] = None, no_commit: bool = False) -> "SqlalchemyBase":logger.debug(f"Creating {self.__class__.__name__} with ID: {self.id} with actor={actor}")if actor:self._set_created_and_updated_by_fields(actor.id)try:- with db_session as session:- session.add(self)- session.commit()- session.refresh(self)- return self+ db_session.add(self)+ if no_commit:+ db_session.flush() # no commit, just flush to get PK+ else:+ db_session.commit()+ db_session.refresh(self)+ return selfexcept (DBAPIError, IntegrityError) as e:self._handle_dbapi_error(e)@@ -455,18 +457,20 @@ class SqlalchemyBase(CommonSqlalchemyMetaMixins, Base):logger.debug(f"{self.__class__.__name__} with ID {self.id} successfully hard deleted")@handle_db_timeout- def update(self, db_session: "Session", actor: Optional["User"] = None) -> "SqlalchemyBase":- logger.debug(f"Updating {self.__class__.__name__} with ID: {self.id} with actor={actor}")+ def update(self, db_session: Session, actor: Optional["User"] = None, no_commit: bool = False) -> "SqlalchemyBase":+ logger.debug(...)if actor:self._set_created_and_updated_by_fields(actor.id)-self.set_updated_at()- with db_session as session:- session.add(self)- session.commit()- session.refresh(self)- return self+ # remove the context manager:+ db_session.add(self)+ if no_commit:+ db_session.flush() # no commit, just flush to get PK+ else:+ db_session.commit()+ db_session.refresh(self)+ return self@classmethod@handle_db_timeoutdiff --git a/letta/services/block_manager.py b/letta/services/block_manager.pyindex cc09c0b16..3bf6996de 100644--- a/letta/services/block_manager.py+++ b/letta/services/block_manager.py@@ -1,10 +1,13 @@import osfrom typing import List, Optional+from sqlalchemy import func+from letta.orm.block import Block as BlockModel+from letta.orm.block_history import BlockHistory+from letta.orm.enums import ActorTypefrom letta.orm.errors import NoResultFoundfrom letta.schemas.agent import AgentState as PydanticAgentState-from letta.schemas.block import Blockfrom letta.schemas.block import Block as PydanticBlockfrom letta.schemas.block import BlockUpdate, Human, Personafrom letta.schemas.user import User as PydanticUser@@ -21,7 +24,7 @@ class BlockManager:self.session_maker = db_context@enforce_types- def create_or_update_block(self, block: Block, actor: PydanticUser) -> PydanticBlock:+ def create_or_update_block(self, block: PydanticBlock, actor: PydanticUser) -> PydanticBlock:"""Create a new block based on the Block schema."""db_block = self.get_block_by_id(block.id, actor)if db_block:@@ -140,3 +143,59 @@ class BlockManager:agents_pydantic = [agent.to_pydantic() for agent in agents_orm]return agents_pydantic++ # Block History Functions++ @enforce_types+ def checkpoint_block(+ self,+ block_id: str,+ actor: PydanticUser,+ agent_id: Optional[str] = None,+ use_preloaded_block: Optional[BlockModel] = None, # TODO: Useful for testing concurrency+ ) -> PydanticBlock:+ """+ Create a new checkpoint for the given Block by copying its+ current state into BlockHistory, using SQLAlchemy's built-in+ version_id_col for concurrency checks.++ Note: We only have a single commit at the end, to avoid weird intermediate states.+ e.g. created a BlockHistory, but the block update failed+ """+ """If `use_preloaded_block` is given, skip re-reading from DB."""+ with self.session_maker() as session:+ # 1) Load the block via the ORM+ if use_preloaded_block is not None:+ block = session.merge(use_preloaded_block)+ else:+ block = BlockModel.read(db_session=session, identifier=block_id, actor=actor)++ # 2) Create a new sequence number for BlockHistory+ current_max_seq = session.query(func.max(BlockHistory.sequence_number)).filter(BlockHistory.block_id == block_id).scalar()+ next_seq = (current_max_seq or 0) + 1++ # 3) Create a snapshot in BlockHistory+ history_entry = BlockHistory(+ organization_id=actor.organization_id,+ block_id=block.id,+ sequence_number=next_seq,+ description=block.description,+ label=block.label,+ value=block.value,+ limit=block.limit,+ metadata_=block.metadata_,+ actor_type=ActorType.LETTA_AGENT if agent_id else ActorType.LETTA_USER,+ actor_id=agent_id if agent_id else actor.id,+ )+ history_entry.create(session, actor=actor, no_commit=True)++ # 4) Update the block’s pointer+ block.current_history_entry_id = history_entry.id++ # 5) Now just flush; SQLAlchemy will:+ block = block.update(db_session=session, actor=actor, no_commit=True)++ session.commit()++ # Return the block’s new state+ return block.to_pydantic()diff --git a/tests/test_managers.py b/tests/test_managers.pyindex 9837a0b3e..938be4c7f 100644--- a/tests/test_managers.py+++ b/tests/test_managers.py@@ -3,19 +3,22 @@ import randomimport stringimport timefrom datetime import datetime, timedelta+from typing import Listimport pytestfrom openai.types.chat.chat_completion_message_tool_call import ChatCompletionMessageToolCall as OpenAIToolCallfrom openai.types.chat.chat_completion_message_tool_call import Function as OpenAIFunctionfrom sqlalchemy.exc import IntegrityError+from sqlalchemy.orm.exc import StaleDataErrorfrom letta.config import LettaConfigfrom letta.constants import BASE_MEMORY_TOOLS, BASE_TOOLS, LETTA_TOOL_EXECUTION_DIR, MCP_TOOL_TAG_NAME_PREFIX, MULTI_AGENT_TOOLSfrom letta.embeddings import embedding_modelfrom letta.functions.functions import derive_openai_json_schema, parse_source_codefrom letta.functions.mcp_client.types import MCPTool-from letta.orm import Base-from letta.orm.enums import JobType, ToolType+from letta.orm import Base, Block+from letta.orm.block_history import BlockHistory+from letta.orm.enums import ActorType, JobType, ToolTypefrom letta.orm.errors import NoResultFound, UniqueConstraintViolationErrorfrom letta.schemas.agent import CreateAgent, UpdateAgentfrom letta.schemas.block import Block as PydanticBlock@@ -46,6 +49,7 @@ from letta.schemas.tool import ToolCreate, ToolUpdatefrom letta.schemas.tool_rule import InitToolRulefrom letta.schemas.user import User as PydanticUserfrom letta.schemas.user import UserUpdate+from letta.server.db import db_contextfrom letta.server.server import SyncServerfrom letta.services.block_manager import BlockManagerfrom letta.services.organization_manager import OrganizationManager@@ -67,11 +71,12 @@ USING_SQLITE = not bool(os.getenv("LETTA_PG_URI"))@pytest.fixture(autouse=True)-def clear_tables():- from letta.server.db import db_context-+def _clear_tables():with db_context() as session:for table in reversed(Base.metadata.sorted_tables): # Reverse to avoid FK issues+ # If this is the block_history table, skip it+ if table.name == "block_history":+ continuesession.execute(table.delete()) # Truncate tablesession.commit()@@ -2366,7 +2371,7 @@ def test_message_listing_text_search(server: SyncServer, hello_world_message_fix# ======================================================================================================================-# Block Manager Tests+# Block Manager Tests - Basic# ======================================================================================================================@@ -2575,6 +2580,153 @@ def test_get_agents_for_block(server: SyncServer, sarah_agent, charles_agent, deassert charles_agent.id in agent_state_ids+# ======================================================================================================================+# Block Manager Tests - History (Undo/Redo/Checkpoint)+# ======================================================================================================================+++def test_checkpoint_creates_history(server: SyncServer, default_user):+ """+ Ensures that calling checkpoint_block creates a BlockHistory row and updates+ the block's current_history_entry_id appropriately.+ """++ block_manager = BlockManager()++ # Create a block+ initial_value = "Initial block content"+ created_block = block_manager.create_or_update_block(PydanticBlock(label="test_checkpoint", value=initial_value), actor=default_user)++ # Act: checkpoint it+ block_manager.checkpoint_block(block_id=created_block.id, actor=default_user)++ with db_context() as session:+ # Get BlockHistory entries for this block+ history_entries: List[BlockHistory] = session.query(BlockHistory).filter(BlockHistory.block_id == created_block.id).all()+ assert len(history_entries) == 1, "Exactly one history entry should be created"+ hist = history_entries[0]++ # Fetch ORM block for internal checks+ db_block = session.get(Block, created_block.id)++ assert hist.sequence_number == 1+ assert hist.value == initial_value+ assert hist.actor_type == ActorType.LETTA_USER+ assert hist.actor_id == default_user.id+ assert db_block.current_history_entry_id == hist.id+++def test_multiple_checkpoints(server: SyncServer, default_user):+ block_manager = BlockManager()++ # Create a block+ block = block_manager.create_or_update_block(PydanticBlock(label="test_multi_checkpoint", value="v1"), actor=default_user)++ # 1) First checkpoint+ block_manager.checkpoint_block(block_id=block.id, actor=default_user)++ # 2) Update block content+ updated_block_data = PydanticBlock(**block.dict())+ updated_block_data.value = "v2"+ block_manager.create_or_update_block(updated_block_data, actor=default_user)++ # 3) Second checkpoint+ block_manager.checkpoint_block(block_id=block.id, actor=default_user)++ with db_context() as session:+ history_entries = (+ session.query(BlockHistory).filter(BlockHistory.block_id == block.id).order_by(BlockHistory.sequence_number.asc()).all()+ )+ assert len(history_entries) == 2, "Should have two history entries"++ # First is seq=1, value='v1'+ assert history_entries[0].sequence_number == 1+ assert history_entries[0].value == "v1"++ # Second is seq=2, value='v2'+ assert history_entries[1].sequence_number == 2+ assert history_entries[1].value == "v2"++ # The block should now point to the second entry+ db_block = session.get(Block, block.id)+ assert db_block.current_history_entry_id == history_entries[1].id+++def test_checkpoint_with_agent_id(server: SyncServer, default_user, sarah_agent):+ """+ Ensures that if we pass agent_id to checkpoint_block, we get+ actor_type=LETTA_AGENT, actor_id=<agent.id> in BlockHistory.+ """+ block_manager = BlockManager()++ # Create a block+ block = block_manager.create_or_update_block(PydanticBlock(label="test_agent_checkpoint", value="Agent content"), actor=default_user)++ # Checkpoint with agent_id+ block_manager.checkpoint_block(block_id=block.id, actor=default_user, agent_id=sarah_agent.id)++ # Verify+ with db_context() as session:+ hist_entry = session.query(BlockHistory).filter(BlockHistory.block_id == block.id).one()+ assert hist_entry.actor_type == ActorType.LETTA_AGENT+ assert hist_entry.actor_id == sarah_agent.id+++def test_checkpoint_with_no_state_change(server: SyncServer, default_user):+ """+ If we call checkpoint_block twice without any edits,+ we expect two entries or only one, depending on your policy.+ """+ block_manager = BlockManager()++ # Create block+ block = block_manager.create_or_update_block(PydanticBlock(label="test_no_change", value="original"), actor=default_user)++ # 1) checkpoint+ block_manager.checkpoint_block(block_id=block.id, actor=default_user)+ # 2) checkpoint again (no changes)+ block_manager.checkpoint_block(block_id=block.id, actor=default_user)++ with db_context() as session:+ all_hist = session.query(BlockHistory).filter(BlockHistory.block_id == block.id).all()+ assert len(all_hist) == 2+++def test_checkpoint_concurrency_stale(server: SyncServer, default_user):+ block_manager = BlockManager()++ # create block+ block = block_manager.create_or_update_block(PydanticBlock(label="test_stale_checkpoint", value="hello"), actor=default_user)++ # session1 loads+ with db_context() as s1:+ block_s1 = s1.get(Block, block.id) # version=1++ # session2 loads+ with db_context() as s2:+ block_s2 = s2.get(Block, block.id) # also version=1++ # session1 checkpoint => version=2+ with db_context() as s1:+ block_s1 = s1.merge(block_s1)+ block_manager.checkpoint_block(+ block_id=block_s1.id,+ actor=default_user,+ use_preloaded_block=block_s1, # let manager use the object in memory+ )+ # commits inside checkpoint_block => version goes to 2++ # session2 tries to checkpoint => sees old version=1 => stale error+ with pytest.raises(StaleDataError):+ with db_context() as s2:+ block_s2 = s2.merge(block_s2)+ block_manager.checkpoint_block(+ block_id=block_s2.id,+ actor=default_user,+ use_preloaded_block=block_s2,+ )++# ======================================================================================================================# Identity Manager Tests# ======================================================================================================================