Andrew Ridgway
76777c98eb
Introduce a shared ConversationService (steward/bot/core.py) that owns the LLM call, history, knowledge-base search, and thread-memory keying behind a normalized ThreadKey, so both Telegram and Matrix drive the same pipeline. - Add steward/bot/matrix.py: a mautrix-python appservice bot that receives Synapse transactions and replies via the client-server API. - Refactor telegram.py handlers into thin wrappers over ConversationService. - Generalize ThreadMemoryStore/ThreadSummary to platform-scoped keys with legacy chat_id:thread_id migration. - Add a matrix config section (homeserver, tokens, room/user allowlists). - Rewrite main.py as async, starting Telegram and/or Matrix on one event loop. - Add mautrix>=0.21.0 dependency. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Steward
Steward is a long-running, AI-assisted personal operations platform designed to reduce cognitive load by acting as a persistent, trustworthy steward of both digital infrastructure and delegated personal objectives.
Features
- Telegram Bot: Group/channel support with thread-based conversations
- Message Threads: Organized conversations with automatic summarization
- Knowledge Base: Stores and retrieves conversation summaries
- LLM Integration: OpenAI-compatible API support
- Tool Calling: Optional MCP/OpenAPI tool server integration
- Flexible Configuration: YAML + environment variables (Kubernetes-ready)
Quick Start
Prerequisites
- Python 3.12+
- Docker & Docker Compose
- Telegram Bot Token (from @BotFather)
- OpenAI API Key
Local Development
- Clone the repository:
git clone https://github.com/djw4/steward.git
cd steward
- Copy
.env.exampleto.envand fill in your values:
cp .env.example .env
# Edit .env with your tokens and IDs
- Create the data directory:
mkdir -p data
- Start with Docker Compose:
docker compose -f docker-compose.dev.yml up --build
Configuration
See CONFIGURATION.md for detailed configuration options.
Running Tests
# Install dev dependencies
pip install -e ".[dev]"
# Run all tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=steward
Pre-commit Hooks
Set up pre-commit hooks to run linting and tests automatically:
pip install pre-commit
pre-commit install
This will run:
ruff checkfor code stylepytestfor tests
On every commit. You can skip with git commit --no-verify if needed.
Development
- Read AGENTS.md for AI agent guidelines
- Read CONFIGURATION.md for config management
- Check .github/workflows/ci.yml for CI/CD pipeline
Deployment
For Kubernetes deployment, see examples in CONFIGURATION.md.
Production image: ghcr.io/djw4/steward:latest
License
See LICENSE file for details.