{"id":"80d79f0c-3779-407e-a7a2-6110ccc8b401","slug":"synapse-ai-hub-forge","kind":"mcp","name":"Forge","summary":"Open-source Python framework to build, orchestrate and deploy AI agents: multi-provider, tool calling, RAG memory and desktop distribution.","owner":"synapse-ai-hub","repoUrl":"https://github.com/synapse-ai-hub/Forge","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":6,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-05-03T02:38:12.000Z","addedAt":"2026-10-21T08:48:04.376Z","logoUrl":"https://avatars.githubusercontent.com/u/337437689?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["search","memory-knowledge"],"tags":["agent-framework","ai-agents","ai-governance","ai-security","ai-tools","chromadb","llm-agents","multi-agent"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T19:55:09.686Z","sample":false,"url":"https://conduits.dev/tools/synapse-ai-hub-forge","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<p align=\"center\">\n  <img src=\"https://github.com/synapse-ai-hub/sources/raw/main/logo_transparente.png\" alt=\"Logo\" width=\"150\">\n</p>\n\n---\n\n<h1 align=\"center\">\n  <img src=\"https://github.com/synapse-ai-hub/sources/raw/main/forge.png\" alt=\"synapseForge\" width=\"420\">\n</h1>\n\n---\n\n<p align=\"center\">\n  <a href=\"./LICENSE\">\n    <img src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" alt=\"License: Apache 2.0\" />\n  </a>\n  &nbsp;\n  <a href=\"https://link.mercadopago.com.ar/synapseforge\">\n    <img src=\"https://github.com/synapse-ai-hub/sources/raw/main/badges/mercadopago-support.svg\" alt=\"Support this project\" />\n  </a>\n</p>\n\n---\n\n<h3 align=\"center\">Forge agents. Ship intelligence.</h3>\n\n---\n\n<p align=\"center\">\n  An open-source forge for creating, equipping, running and shipping autonomous AI agents.\n\n---\n\n<p align=\"center\">\n  <sub>CLI · Agent Factory · Distribution</sub>\n</p>\n</p>\n\n---\n\n```\n    FORGE             EQUIP             RUN              SHIP\n    ─────             ─────             ───              ────\n    Agents            Permissions       AgentLoop        Docker\n    Skills            Providers         Tool calling     Desktop app\n    Tools             Models            RAG search       Portable zip\n    Knowledge                           Memory           Ready to ship\n                                        Streaming SSE\n```\n\n---\n\n## What is synapseForge?\n\nMost AI agent tools give you pieces and rules. synapseForge gives you the forge.\n\nYou don't assemble an agent. You forge a system.\n\nsynapseForge is designed around a simple idea: agents should be built as systems, not assembled from prompts.\n\nDefine your agents, equip them with skills and tools, connect them to your data sources, and ship a self-contained application — from `pip install` to a distributable build (Docker, desktop app or portable zip).\n\n### A forge that can extend itself\n\nCreate agents, skills, tools and workflows through an LLM-assisted interview. synapseForge doesn't just run agents — it can create the capabilities they need.\n\n---\n\n## How it works\n\n### You build\n\n- **Agents** — define roles, permissions and behavior in `.md` files\n- **Skills** — structured knowledge packages with references and frontmatter\n- **Tools** — native (filesystem, web, shell, email) or external `.py` files\n- **RAG collections** — upload files and web pages, indexed with vector embeddings\n- **Workflows** — deterministic DAGs of agent, tool, RAG and shell nodes defined in YAML\n\n### The Forge\n\nThe Forge turns those definitions into autonomous systems.\n\n- **Permission engine** — deny-by-default, per-agent, with wildcards and groups\n- **Security** — rules against prompt injection, data leaks and dangerous commands or SQL; they go in the router prompt or, with the decision model enabled, the decision model enforces them as a guardrail on the user message\n- **Agent loop** — iterative reasoning → tool calling → execution → continuation, with streaming SSE\n- **Workflows** — deterministic DAG execution started with a play button: sequential steps, same-step nodes in parallel, background runs with retries, persisted results and notifications\n- **Memory** — persistent conversation indexing and cross-session retrieval\n- **Multi-provider LLM** — Ollama (local), curated cloud providers (OpenAI-compatible + Google)\n- **MCP integration** — connect external tool servers via the Model Context Protocol (stdio, HTTP or SSE), with an on/off switch per server\n- **Scheduler** — workflows with a `schedule` block run on a schedule, notify via UI and Telegram\n\n### You ship\n\n```bash\nsynapseForge init my-project      # scaffold with GUI\nsynapseForge run .                # develop locally\nsynapseForge launch -n my-app     # build a desktop app / portable zip\ndocker compose up --build -d      # or deploy with Docker\n```\n\nThe result is a self-contained application distribution. Choose the modality that fits: a **Docker** container (autocontained or backend-only), a **desktop app** (embedded Python + native launcher), or a **portable zip** ready to hand to anyone.\n\n---\n\n## Quick start\n\n> Currently available on [PyPI](https://pypi.org/project/synapseForge/).\n\n```bash\npip install synapseForge\n\n# Create a project (interactive GUI)\nsynapseForge init my-project\ncd my-project\n\n# Start in development mode\nsynapseForge run .\n```\n\nOn first launch, configure an API key from any curated cloud provider (all offer free tiers) and press **Apply**. Ollama is optional. The knowledge base requires a Google key, and voice notes require a Groq key.\n\n---\n\n## CLI\n\n| Command | What it does |\n|---------|-------------|\n| `synapseForge init [dir]` | Create a project with interactive GUI |\n| `synapseForge launch -p <path> -n <name>` | Build a desktop app / portable distribution zip |\n| `synapseForge colors [dir]` | Edit project colors live |\n| `synapseForge run [dir]` | Start development servers |\n| `synapseForge update [dir]` | Update project to latest template (preserves data) |\n\n<p align=\"center\">\n  <img src=\"https://github.com/synapse-ai-hub/sources/raw/main/videos/pipeline-en.gif\" alt=\"synapseForge pipeline: from pip install to distributable app\" width=\"100%\">\n</p>\n\n---\n\n## Architecture\n\n### Backend\n\nFastAPI application with REST/SSE routers. The agent framework lives in `backend/agent/`: AgentLoop with native tool calling, tools registry (native + external + MCP), SQLite sessions, per-agent permissions, skills, RAG (ChromaDB) and long-term memory.\n\n**Native tools**: `read`, `write`, `edit`, `glob`, `grep`, `list_dir`, `webfetch`, `websearch`, `shell`, `task` (sub-agent delegation), `skill`, `reference`, `rag`, `search_memory`, `check_email`, `send_email`, `query_model_capabilities`.\n\n### Workflows\n\nDeterministic flows defined as flat YAML files (`~/.config/synapseForge/workflows/<name>.yaml`, one file per workflow). Each workflow is a list of nodes with `id`, `type` (`agent`, `tool`, `rag` or `run`), `step` (integer from 1) and exactly one node with `final: true`. Nodes in the same step run in parallel with a barrier; different steps run sequentially. Agent nodes run in memory, without a session, with that agent's own prompt, permissions and parameters; `run` nodes execute shell commands GitHub-Actions style.\n\nA workflow runs from the **play** button of its card in the agent info panel. It runs in the background, in parallel with the chat, and never opens a session nor writes in `messages`; while it runs the card shows \"Ejecutando…\" and can be cancelled. Before running, the backend verifies that every referenced agent, tool and collection exists — if something is missing, it says what instead of executing. Workflows run under least-privilege permissions derived from their own nodes. Every node is committed with its full result: if a node fails or the app stops, the run is retried (3 attempts in total, exponential backoff) from the first node without a confirmed result. When every node completes, a judge (the decision model, or the chat model if it is not enabled) checks the result; a definitive failure is explained in plain language. The result arrives as a persisted notification in the header bell, with the unread count; the run, every node (with the tokens, cost and time of its LLM calls and the tools an agent node called), the node commits and the calls of the judge are stored in their own tables (`workflow_runs` and `workflow_run_steps`). Only \"Revisar con el agente\" opens a session, a new one with the result. A dedicated creator (interview + validation + user approval) generates the YAML; the prompt of each `agent` node lives in a toml file in `workflows/prompts/`.\n\n### Checkpoints and decision model\n\nEvery tool call the agent dispatches is recorded in SQLite before it runs and confirmed when its result commits. If a flow is cut (cancellation, crash), the next turn starts with the unconfirmed work injected as context, so the agent resumes instead of repeating what was already done. The record is deleted only when the step closes with a validated final answer.\n\nAn optional **decision model** (System One) can be enabled in **Config**, independent of the chat model. It returns typed answers with a confidence level instead of text, and makes three checks: whether the user message tries to violate the security rules (guardrail: it is blocked before the chat model runs), whether a final answer really closes the step, and whether a new user message continues the pending work or asks for something else (in which case the pending work is discarded). Models come from the models.dev decision catalog, synced at most once every 24 hours, and the provider's API key must be saved. With the decision model disabled, there is no guardrail check (the security rules go in the router prompt), the agent accepts its own final answer and always keeps the pending work, with no extra calls.\n\n### Frontend\n\nReact/Vite/TypeScript SPA with Tailwind v4 and shadcn/ui. Multi-page: chat, skill, tool, agent and workflow creation, RAG management, docs. SSE streaming, tool call visualization, context window gauge, scheduled tasks, usage and billing, metrics dashboard, Telegram toggle.\n\n### Providers\n\n| Provider | Type | Notes |\n|----------|------|-------|\n| Ollama | Local | Optional, requires local install; listed only while running |\n| Google | Cloud | Gemini models + RAG embeddings; free tier |\n| OpenAI-compatible | Cloud | Groq, OpenRouter, OpenAI, DeepSeek, xAI, Together AI, Fireworks AI, Cerebras, Mistral AI, Perplexity, Meta, Moonshot AI, Zhipu AI, Alibaba; free tiers |\n\nCloud providers are curated in-app: each API key is validated live against its own API and stored encrypted (Fernet) in SQLite, and a provider is listed only while its key is saved. No environment variables needed. Models come from the models.dev catalog cached in SQLite — select provider + model explicitly and press **Apply**.\n\n### Knowledge base (RAG)\n\nChromaDB with Gemini embeddings (`gemini-embedding-2`) via the Google provider. Upload files and web pages — content is extracted, chunked and indexed for semantic retrieval. Chunking (chunk size and overlap, in characters) is configurable per upload from the UI (defaults: chunk 500, overlap 60). Requires a Google API key: without it, the knowledge base stays disabled and everything else runs normally. Long-term memory: every conversation turn is automatically indexed and searchable across sessions via `search_memory`.\n\n### Telegram\n\nRemote control for the agent. Send messages, switch models, create skills/tools, manage scheduled tasks — all through Telegram. The bot bridges to the same chat flow the frontend uses.\n\n### Scheduled tasks\n\nA scheduled task is a workflow whose YAML has a `schedule` block (time `HH:MM` + weekdays). Tasks are created with the workflow creator — from the header Agenda (name, description, schedules and the resources the workflow will use) or with `/agendar` on Telegram — and run in the workflow engine like any run (retries, judge, notifications). The Agenda panel also edits schedules, runs tasks with play, cancels them and deletes them (workflow + runs + notifications). The backend checks every 20 seconds for schedules matching the current minute; the system timezone is used, with no configuration.\n\n### Usage and billing\n\nThe header has two buttons: **Usage** and **Billing**, with the current month's data.\n\n**Usage** shows the month's consumption: requests, total tokens, spend in USD and the input/output token breakdown, plus per-provider detail and configured limits.\n\n**Billing** shows the month's spend per provider and model, with provider and model filters. Each model shows input and output tokens with their rate and cost, total cost and request count. It also configures spend limits per provider or model: when a limit is reached, requests are blocked until it is raised.\n\nAll cloud model activity is tracked: chat, tools, creators, agenda, embeddings and transcriptions. Local models (Ollama) have no cost and are not counted.\n\n---\n\n## Project structure\n\n```plaintext\nsynapseForge/\n├─ synapseforge/              # CLI + tkinter GUIs\n├─ pipeline/                  # init / update / launch pipelines + template.zip\n├─ backend/                   # FastAPI + Agent Framework\n│  ├─ agent/                  #   Agent, loop, LLM calls, tools, sessions, permissions\n│  ├─ routes/                 #   API endpoints, one module per topic\n│  └─ telegram/               #   Telegram bot (polling, dispatch, commands)\n├─ frontend/                  # React/Vite/TypeScript SPA\n├─ config/                    # Project placeholder values (replace.json)\n├─ src/                       # Template assets (company logo, project README template)\n├─ store/                     # Skills and tools store\n├─ .commands/                 # Local dev commands (sync, push, template, test)\n├─ on_boarding/               # Contributor guides and Git workflow\n├─ tests/                     # Declarative E2E suites (YAML) and unit tests\n└─ pyproject.toml             # Package config\n```\n\n`pipeline/template.zip` is the project template that `synapseForge init` and `synapseForge update` download. It is regenerated from `backend/` and `frontend/` (without `node_modules`, `__pycache__` or the local database) with the `template` quick command.\n\n---\n\n## User configuration\n\n```plaintext\n~/.config/synapseForge/\n├─ skills/            # Installed skills\n├─ tools/             # Custom tools (.py)\n├─ agents/            # Agent definitions (.md)\n├─ workflows/         # Deterministic workflows (<name>.yaml)\n├─ knowledge/         # RAG collections (ChromaDB)\n├─ mcp.json           # MCP servers\n└─ .secret_key        # Key that encrypts the stored API keys (generated)\n```\n\n---\n\n## Testing\n\nDeclarative E2E suite in `tests/e2e/`. YAML scenarios drive the real backend — chat via SSE, direct API calls — asserting on contracts and structure.\n\n```bash\npython -m tests.e2e.runner                # all scenarios\npython -m tests.e2e.runner --only rag     # filter by name\n```\n\nOther suites:\n\n```bash\npython -m tests.workflows.runner          # workflow validation and execution (running backend)\npython -m tests.checkpoints.runner        # checkpoints against the real agent.db (running backend + LLM)\npytest tests/frontier                     # checkpoint unit tests\npytest tests/prompts                      # Jinja prompts, permission format and security rules\npytest tests/mcp                          # MCP servers over stdio, HTTP and SSE, and the on/off switch\npytest tests/loop                         # early exits of the agent loop\npytest tests/feedback                     # thumbs up / down on answers\npython -m tests.decisor.decision_cli      # decision model, manual run\n```\n\n---\n\n## Docker\n\nDeploy the app as a container. Two targets are available in `docker-compose.yml`:\n\n- **`app`** — autocontained: builds the frontend and serves it from the backend in a single container.\n- **`backend`** — backend only, for separated deployments (e.g. ACI).\n\n```bash\ndocker compose up --build -d\n# App at http://localhost:8000\n```\n\n---\n\n## Tech Stack\n\n[![Python](https://github.com/synapse-ai-hub/sources/raw/main/badges/python.svg)](https://www.python.org/)\n[![FastAPI](https://github.com/synapse-ai-hub/sources/raw/main/badges/fastapi.svg)](https://fastapi.tiangolo.com/)\n[![SQLite](https://github.com/synapse-ai-hub/sources/raw/main/badges/sqlite.svg)](https://www.sqlite.org/)\n[![ChromaDB](https://github.com/synapse-ai-hub/sources/raw/main/badges/chromadb.svg)](https://www.trychroma.com/)\n[![React](https://github.com/synapse-ai-hub/sources/raw/main/badges/react.svg)](https://react.dev/)\n[![TypeScript](https://github.com/synapse-ai-hub/sources/raw/main/badges/typescript.svg)](https://www.typescriptlang.org/)\n[![Vite](https://github.com/synapse-ai-hub/sources/raw/main/badges/vite.svg)](https://vite.dev/)\n[![Tailwind](https://github.com/synapse-ai-hub/sources/raw/main/badges/tailwind.svg)](https://tailwindcss.com/)\n[![shadcn/ui](https://img.shields.io/badge/shadcn%2Fui-UI-555?labelColor=d0d4dc&logo=shadcnui&logoColor=111)](https://ui.shadcn.com/)\n[![Node.js](https://github.com/synapse-ai-hub/sources/raw/main/badges/nodejs.svg)](https://nodejs.org/)\n[![PyInstaller](https://github.com/synapse-ai-hub/sources/raw/main/badges/pyinstaller.svg)](https://pyinstaller.org/)\n[![Docker](https://github.com/synapse-ai-hub/sources/raw/main/badges/docker.svg)](https://www.docker.com/)\n[![Telegram](https://github.com/synapse-ai-hub/sources/raw/main/badges/telegram.svg)](https://telegram.org/)\n[![PyPI](https://github.com/synapse-ai-hub/sources/raw/main/badges/pypi.svg)](https://pypi.org/)\n[![Groq](https://github.com/synapse-ai-hub/sources/raw/main/badges/groq.svg)](https://groq.com/)\n[![Google Gemini](https://github.com/synapse-ai-hub/sources/raw/main/badges/gemini.svg)](https://ai.google.dev/)\n[![OpenRouter](https://github.com/synapse-ai-hub/sources/raw/main/badges/openrouter.svg)](https://openrouter.ai/)\n[![Ollama](https://img.shields.io/badge/Ollama-Local-555?labelColor=d0d4dc&logo=ollama&logoColor=111)](https://ollama.com/)\n\n---\n\n## Support this project\n\nsynapseForge is free and open source. If you find it useful, consider supporting its development with a [donation via Mercado Pago](https://link.mercadopago.com.ar/synapseforge).\n\n---\n\n## License\n\nThis project is licensed under the terms specified in the [LICENSE](./LICENSE) file.\n\n---\n\nCopyright (c) 2026 SYNAPSE AI SAS\n\n---\n\n*The forge is heating up...*\n"}