[Project] 2. Synapulse — A Self-Hosted Personal AI Assistant

Overview

Synapulse (Synapse + Pulse) is a self-hosted personal AI assistant that lives in your Discord server. The idea came from OpenClaw — after seeing what it could do, I decided to build the personal assistant I had always wanted, one that is lightweight, transparent, and fully under my control.

• GitHub: GOODDAYDAY/Synapulse

Demo

Weather query	Web search + recommendation

Reminder (notify mode)	Reminder (prompt mode)

File creation + send

Features

Architecture

Tech Stack

Project Structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

apps/bot/
├── main.py                    # Entry point
├── config/                    # Settings, prompts, logging
├── core/
│   ├── handler.py             # Bootstrap: wire all components via DI
│   ├── loader.py              # Auto-discover tools and jobs from folders
│   ├── mention.py             # Tool-call loop, memory load/save, summarization
│   └── reminder.py            # Background reminder checker
config/                          # Runtime config (models.yaml, mcp.json, jobs.json)
output/                          # Runtime output (logs, data)
├── provider/
│   ├── base.py                # OpenAIProvider, AnthropicProvider
│   ├── endpoint.py            # EndpointPool: rotation, rate-limit fallback
│   └── copilot/auth.py        # GitHub OAuth Device Flow
├── channel/
│   └── discord/client.py      # Discord bot integration
├── tool/                      # Native tools (auto-discovered)
│   ├── base.py                # BaseTool, OpenAITool, AnthropicTool
│   ├── brave_search/          # Web search
│   ├── local_files/           # Read/write local files (sandboxed)
│   ├── memo/                  # Notes management
│   ├── task/                  # Todo list
│   ├── reminder/              # Reminders
│   ├── weather/               # Weather via OpenWeatherMap
│   ├── shell_exec/            # Shell commands (with safety blacklist)
│   └── mcp_server/            # Manage MCP connections via chat
├── job/                       # Background jobs (auto-discovered)
│   ├── cron.py                # CronJob base with hot-reload
│   ├── gmail/                 # Gmail monitoring
│   ├── outlook/               # Outlook monitoring
│   └── qqmail/                # QQ Mail monitoring
├── mcp/
│   └── client.py              # MCPManager: spawn, discover, route
└── memory/
    └── database.py            # JSON file persistence

Core Loop

The tool-call loop in core/mention.py:

1. Load memory: conversation history (last 20 turns) + summary from database
2. Load tasks: pending to-dos injected into system prompt
3. Build prompts: system prompt (tool hints + memory + tasks) + user prompt (stored history + channel history + referenced message + current message)
4. Call AI: send messages to provider
5. Tool-call loop (max 10 rounds):
   • If AI returns text → save turn to database, maybe summarize, return text
   • If AI requests tool calls:
     • Compress old tool results to save tokens
     • Validate arguments against JSON Schema
     • Execute tool (native or MCP)
     • Append result to messages
     • Sleep 1s (rate-limit protection)
     • Continue loop
6. If max rounds hit → return “got stuck in a loop” message

Memory System

Storage: JSON files — conversations.json, summaries.json, memos.json, reminders.json, tasks.json

Memory flow:

Summarization: cascading — new summary includes previous summary + new turns. Old turns deleted only after summarization succeeds.

Tool System

Tools inherit from BaseTool with format mixins:

1
2
3
4
5
6
7
8

class Tool(OpenAITool, AnthropicTool):
    name = "my_tool"
    description = "What it does"
    parameters = {...}  # JSON Schema
    usage_hint = "Short routing hint for system prompt"

    async def execute(self, **kwargs) -> str:
        return "result"

Auto-discovery: core/loader.py scans tool/ directory for handler.py files, loads Tool() class, calls validate().

Dependency injection: core injects db (Database), send_file callback, and channel_id into tools at startup or per-message.

Format-agnostic: each tool has to_openai() and to_anthropic() methods. Same tool works with both APIs.

MCP tools: MCPManager spawns MCP servers as subprocesses, discovers tools via MCP protocol, wraps them in MCPToolWrapper (duck-typed to match native tool interface). Hot-reload checks config every 30s.

MCP On-Demand Loading

A key optimization: MCP tools are NOT loaded into the provider’s tool list at startup. Instead:

1. At startup, only native tool schemas are sent to the AI (saves tokens)
2. MCP tool names are listed as hints in the system prompt
3. When the AI needs an MCP tool, it calls mcp_server(action="use_tools", tools=[...]) to activate specific tools
4. Requested schemas are added to the provider’s tool list on-demand for the current request only

This avoids sending 100+ MCP tool schemas on every API call, significantly reducing token usage.

Model Rotation & Fallback

The EndpointPool manages multiple AI endpoints defined in config/models.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

models:
  - name: github-gpt4o
    protocol: openai
    base_url: https://models.inference.ai.azure.com
    api_key: ${GITHUB_TOKEN}
    model: gpt-4o
    tags: [large, coding]
    priority: 0
  - name: ollama-local
    protocol: openai
    base_url: http://localhost:11434
    model: llama3
    tags: [local]
    priority: 1

• Tag-based routing: request a specific capability (e.g., large, coding, local)
• Round-robin rotation within the same priority level
• Rate-limit fallback: on 429, mark endpoint as cooldown (respects Retry-After header), try next
• Hot-reload: config file changes detected every 30s, preserving cooldown state

Shell Execution Safety

The shell_exec tool runs shell commands with multiple safety layers:

• Dangerous command blacklist: blocks rm -rf /, mkfs, shutdown, sudo, etc.
• Configurable timeout: 1–120 seconds per command
• Output truncation: results capped at 10,000 chars
• Sandboxed working directory: restricted to paths in LOCAL_FILES_ALLOWED_PATHS

Comparison: OpenClaw vs Nanobot vs Synapulse

OpenClaw is a mature, full-featured personal AI assistant. Nanobot distills its core into “99% fewer lines of code”. Synapulse is my attempt to learn from both and build a minimal personal assistant for my own use — it is far simpler and less capable than either, but the process of building it taught me a lot about how agent systems work under the hood. The comparison below is meant to document what I learned, not to suggest Synapulse is on the same level.

Overview

Agent Loop

The agent loop is the core mechanism that orchestrates LLM calls and tool execution.

OpenClaw: the most sophisticated. The core delegates the agentic loop to a closed-source Pi SDK. It observes tool calls and results via subscription callbacks. On failure, it has a multi-layer recovery system — rotate auth profiles, auto-compact context on overflow (up to 3 attempts), truncate oversized tool results, and fall back to a different model.

Nanobot: runs up to 40 rounds. The AgentLoop class consumes messages from an async bus, calls provider.chat_with_retry(), executes tools via self.tools.execute(), and appends results. It tracks active tasks per session and uses locking for concurrency control.

Synapulse: much simpler by comparison. A plain for loop up to 10 rounds. Each round: call provider → check for tool calls → validate JSON Schema → execute → append result → sleep 1s. No retry, no fallback — errors are caught and returned as text. It gets the job done for personal use but lacks the robustness of the other two.

Memory

OpenClaw: memory is deeply integrated into the Pi SDK’s session manager. Compaction is triggered automatically when context overflows. The session file is a binary format, making it opaque to inspect or modify.

Nanobot: uses a two-layer memory system. MEMORY.md stores long-term facts (consolidated knowledge), and HISTORY.md stores a timestamped log of events (grep-searchable). Messages are append-only in JSONL format for LLM cache efficiency — consolidation writes to the markdown files but does NOT modify the message list.

Synapulse: the simplest approach. Per-turn save to JSON files. When turns exceed 20, old turns are summarized via an LLM call (cascading: new summary includes previous summary + new turns). Old turns deleted only after summarization succeeds. Compared to Nanobot’s two-layer system, this is more naive — but the JSON format is trivially inspectable and editable, which helps during development.

Tool System

OpenClaw: tools are pre-compiled into the Pi SDK. Custom tools are added via a plugin system. The SDK owns tool execution — the core system only observes via callbacks.

Nanobot: tools are subclasses of a Tool ABC with name, description, parameters (JSON Schema), and execute(). Built-in tools include file operations, shell execution, web search, subagent spawning, and cron scheduling. The tool base class includes schema-driven type casting and recursive validation.

Synapulse: borrows the same pattern from Nanobot but adds format mixins. A tool inherits from OpenAITool and/or AnthropicTool to declare which LLM APIs it supports. Tools are auto-discovered by scanning directories. Dependencies (database, file sender) are injected by the core — a small design choice learned from studying the other two projects.

Key Takeaways

OpenClaw is a full-featured, production-grade system with sophisticated error recovery, multi-channel support, and multi-agent orchestration. It is the most mature and capable of the three.

Nanobot delivers the core of OpenClaw in ~4K lines of Python. It supports 10+ channels, has a clean two-layer memory system, and adds subagent support. A remarkable achievement in code density.

Synapulse is a personal learning project (~2K lines). Compared to the other two, it lacks multi-channel support, subagent capability, and sophisticated error recovery. What it does have is simplicity — the entire codebase is small enough to read in one sitting, which was the whole point: to understand how agent systems work by building one from scratch.

Configuration

Environment Variables (.env)

Multi-Endpoint Rotation (config/models.yaml)

Multiple AI endpoints with tag-based routing, priority, and automatic rate-limit fallback. Hot-reloads every 30s.

MCP Servers (config/mcp.json)

55 pre-configured MCP servers (all disabled by default). Enable by setting "enabled": true. Servers can also be added dynamically via Discord chat.

Requirements

• Python 3.11+
• Discord bot token
• An LLM API endpoint (or use mock provider for testing)

Source Code

• GitHub: GOODDAYDAY/Synapulse
• License: MIT