英语| 韩语
Sidekick
A personal AI agent that remembers you, schedules tasks, and extends with custom tools.
Quick Start · Features · Architecture · Dev Guide
______________________________________________________________________
为什么是Sidekick？
通用AI聊天机器人在每次对话后都会忘记你，它们的功能是固定的。
Sidekick是不同的 --它记住你的上下文，按计划运行任务，你可以添加任何具有单一功能的工具。
| 通用聊天机器人 | Sidekick |
|---|---|
| 每次重复相同的上下文 | 记住过去的对话、项目、偏好 |
| 仅限实时聊天 | “1小时后提醒我”-计划任务 |
| 固定功能 | 添加工具 @register_tool |
| 原始提示输入 | !briefing --自定义快捷方式命令 |
快速开始
单线安装
curl -fsSL https://raw.githubusercontent.com/lee-lou2/sidekick/main/install.sh | bash手动设置
git clone https://github.com/lee-lou2/sidekick.git
cd sidekick
cp .env.example .env # Set your GOOGLE_API_KEY
make run # Auto-installs deps, picks run modemake run 自动处理uv安装、依赖关系和运行模式选择。运行模式
Slack机器人：
uv run python src/interfaces/slack/bot.pyREST API：
uv run uvicorn src.interfaces.api:app --port 8000API示例：
curl -X POST http://localhost:8000/run \
-H "Content-Type: application/json" \
-H "X-API-Key: $API_AUTH_KEY" \
-d '{
"prompt": "Summarize today'\''s news",
"webhook_url": "https://your-server.com/webhook"
}'特性
记忆——一种能够记忆的人工智能
You: I'm working on a side project with FastAPI
Agent: What kind of service are you building?
(days later)
You: My API feels slow
Agent: Your FastAPI project? Usually it's DB queries or sync I/O.
Want me to profile a specific endpoint?- 自动记住姓名、项目、沟通方式
- 不需要明确的“记住这一点”——自然学习
- 每用户隔离内存（多用户安全）
调度器——定时任务
"Summarize today's news in 1 minute"
"Remind me about the meeting at 5 PM"
"Check my email tomorrow at 10 AM"- 解析韩语和英语时间表达
- SQLite持久性——在机器人重启后幸存下来
List my scheduled tasks,Cancel task abc123
自定义命令
将常用提示另存为快捷命令：
You: Create a command !briefing with prompt "Summarize top 3 news today"
Agent: Command 'briefing' created!
(later)
You: !briefing
Agent: [Today's news summary...]- AI自动改善您的提示
- 自动推荐相关工具
- 用户只能修改自己的命令
即插即用工具
# src/tools/custom/weather.py
import os
from src.tools.registry import register_tool
@register_tool
def get_weather(city: str) -> str:
"""Get the weather for a city."""
api_key = os.getenv("WEATHER_API_KEY")
return fetch_weather_api(city, api_key)删除文件，重新启动，完成。 没有其他要修改的文件。
- 环境变量：添加到
.env - 重新启动：
make run
工具共享
与他人共享工具并安装共享工具：
make tool-upload # Upload → get a temporary link
make tool-install # Install from a link → auto-validates Python syntax建筑
graph TB
subgraph Interfaces
Slack[Slack Bot]
API[REST API]
end
subgraph Middleware
Pre[Preprocessing]
Guard[Guardrails]
Post[Postprocessing]
end
subgraph Core
Agent[AgentRunner]
Memory[Memory]
Scheduler[Scheduler]
Commands[Commands]
end
subgraph Tools
Custom["@register_tool"]
MCP[MCP Servers]
end
Slack --> Pre
API --> Pre
Pre --> Agent
Agent --> Guard
Guard --> Custom
Guard --> MCP
Agent --> Post
Agent -.-> Memory
Agent -.-> Scheduler
Agent -.-> Commands| 层 | 责任 | 示例 |
|---|---|---|
| 接口 | 入口点、协议处理 | Slack Socket模式、FastAPI |
| 中间件 | 跨领域问题 | 安全护栏、预处理 |
| 核心 | 业务逻辑 | 代理、内存、调度器 |
| 工具 | 工具定义和执行 | 自定义功能，MCP服务器 |
Directory Structure
src/
├── interfaces/ # Entry points
│ ├── slack/ # Slack (Socket Mode, lazy listener)
│ └── api/ # FastAPI (async, webhooks)
├── middleware/
│ ├── guardrails/ # Security — sensitive file blocking, write restrictions
│ ├── preprocessing/ # Command parsing, context setup
│ └── postprocessing/ # Response formatting (minimal)
├── core/
│ ├── agent/ # AgentRunner, AgentFactory, utils
│ ├── memory/ # Graph-based user context
│ ├── scheduler/ # APScheduler + SQLite
│ ├── commands/ # Custom command CRUD
│ └── lifecycle.py # Component start/stop management
├── tools/
│ ├── custom/ # @register_tool functions
│ ├── mcp/ # MCP server definitions (gitignored)
│ ├── mcp_registry.py # MCPServerConfig, register_mcp_server()
│ ├── mcp_client.py # MCPManager (multi-server connections)
│ ├── catalog.py # Unified tool catalog
│ └── registry.py # Auto-registration logic
└── utils/ # Logging, formatters, etc.设计原则
| 原理 | 实施 |
|---|---|
| 松耦合 | 即插即用工具/MCP服务器——按文件添加或删除 |
| 纵深防御 | 护栏保护所有工具类型（MCP+定制） |
| 生命周期管理 | 具有有序启动/停止功能的Singleton组件 |
| MCP集成 | 连接文件系统、git、GitHub等 |
| 可观测性 | Pydantic Logfire集成 |
环境变量
| 变量 | 必填 | 描述 |
|---|---|---|
GOOGLE_API_KEY | 是 | Gemini API密钥 |
SLACK_BOT_TOKEN | Slack机器人令牌 | |
SLACK_APP_TOKEN | Slack应用令牌 | |
API_AUTH_KEY | REST API身份验证密钥（如果未设置，则禁用） | |
GITHUB_TOKEN | MCP GitHub集成 |
看 .env.示例 对于所有核心变量。自定义工具变量进入 .env 只有。
发展
make # Help
make test # Core tests
make test-all # All tests (including custom tools)
make lint # Lint + auto-fix
make format # Code formatting
make tool-install # Install external tools
make tool-upload # Upload tools for sharing
make edit-env # Edit .env看 代理商.md 获取完整的开发指南。
贡献
欢迎投稿！方法如下：
- 克隆该仓库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 按照中的风格指南进行操作 代理商.md
- 跑
make lint && make test在承诺之前 - 提交拉取请求
添加工具
最简单的贡献方式是添加一个新工具：
# src/tools/custom/your_tool.py
from src.tools.registry import register_tool
@register_tool
def your_tool(param: str) -> str:
"""What this tool does."""
return f"Result: {param}"就是这样。没有其他文件可以修改。
局限性
- 添加后需要重新启动工具
- 基于SQLite（建议使用单实例）
- 专为个人/小型团队使用而设计
许可证
麻省理工学院