How jackmannx/sawtooth-memory works
Sawtooth Memory is a hierarchical memory framework for LLM agents. An application adds conversation messages to a context manager, which returns promptly while local monitoring, entity extraction, and folding prepare work for background compression. A worker updates archival memory; prompt compilation retrieves useful context from the working, entity, archival, and optional semantic layers for the agent’s next LLM call. The README documents sync operation, provider backends, adapters, and storage options. Some connections are based on documented behavior because the corresponding implementation excerpts were not provided.
Main entry points: middleware.py Async context manager · base.py Storage interface · state.py Hierarchical state · worker.py Background worker
Components 25
Memory API
- Async context manager
sawtooth_memory/middleware.py - Sync context manager
sawtooth_memory/sync_manager.py
Ingest and Compression
- Token monitor
sawtooth_memory/monitor.py - Deterministic NER
sawtooth_memory/ner.py - Entity guard
sawtooth_memory/entity_guard.py - Intent planner
sawtooth_memory/intent_planner.py - Observation compaction
sawtooth_memory/observation_crush.py - History folding
sawtooth_memory/fold_unit.py - Background worker
sawtooth_memory/worker.py - Compression engine
sawtooth_memory/compressor.py - LLM provider adapters
sawtooth_memory/providers/adapters.py
Context and Retrieval
- Hierarchical state
sawtooth_memory/state.py - Prompt compiler
sawtooth_memory/prompt_compiler.py - Semantic indexer
sawtooth_memory/l3_indexer.py - Embedding provider
sawtooth_memory/embeddings/factory.py
Adapters and Events
- LangChain adapter
sawtooth_memory/integrations/langchain_adapter.py - LangGraph adapter
sawtooth_memory/integrations/langgraph/adapter.py - LangGraph nodes
sawtooth_memory/integrations/langgraph/graph.py - Event bus
sawtooth_memory/events/bus.py - Compression journal
sawtooth_memory/journal.py
Persistence
- Storage interface
sawtooth_memory/storage/base.py - Postgres adapter
sawtooth_memory/storage/postgres_adapter.py - Redis adapter
sawtooth_memory/storage/redis_adapter.py
Other components
- Agent application
- LLM services
Connections 28
- Agent application → Async context manager: adds messages
- Agent application → Sync context manager: adds messages
- Async context manager → Hierarchical state: updates
- Sync context manager → Hierarchical state: updates
- Async context manager → Token monitor: checks thresholds
- Async context manager → Deterministic NER: scans messages
- Async context manager → Entity guard: protects entities
- Async context manager → Intent planner: plans retrieval
- Async context manager → Observation compaction: compacts observations
- Async context manager → Background worker: queues compression
- Background worker → Compression engine: compresses history
- Compression engine → LLM provider adapters: formats requests
- LLM provider adapters → LLM services: calls provider
- Background worker → Hierarchical state: merges results
- Async context manager → Prompt compiler: compiles context
- Prompt compiler → Hierarchical state: reads memory layers
- Async context manager → Semantic indexer: indexes archive
- Semantic indexer → Embedding provider: creates embeddings
- Semantic indexer → Storage interface: stores vectors
- Async context manager → Storage interface: loads and saves state
- Storage interface → Postgres adapter: persists state
- Storage interface → Redis adapter: persists state
- Agent application → LangChain adapter: uses history adapter
- LangChain adapter → Async context manager: adds and reads messages
- LangGraph nodes → LangGraph adapter: syncs and compiles
- LangGraph adapter → Async context manager: adds messages
- Async context manager → Event bus: emits events
- Event bus → Compression journal: dispatches journal events