Fumino Engine

Fumino Engine

> 文乃 — Where knowledge flows, voices follow.

> Open-source AI agent engine that connects intelligent workflows to any platform — Discord, Telegram, REST API, CLI, and beyond.

[](https://opensource.org/licenses/Apache-2.0) [](https://bun.sh) [](https://www.typescriptlang.org/) []() []()

Named after Fumino Furuhashi (文乃) from We Never Learn — 文 (writing, language, knowledge) + 乃 (flowing from). We build systems that communicate well.

---

⚠️ Alpha Disclaimer

This project is in early alpha and NOT ready for production use.

• Many features are partially implemented or have known bugs
• APIs and config format may change without notice
• Database schema may require manual migration between versions
• Expect crashes, edge cases, and incomplete error handling

This is a vibe-coded project — built rapidly with AI-assisted development (Claude, GPT, Gemini via multi-agent orchestration). The architecture is intentional and well-documented, but the implementation is moving fast and breaking things. Contributions, bug reports, and patience are all welcome.

If you want a stable AI agent framework today, check out Hermes Agent (Python) or LangGraph (Python). Fumino aims to be the TypeScript alternative — we're just not there yet.

---

What is Fumino Engine?

Fumino is a self-hostable AI agent engine — not just a chatbot. It can reason, use tools, remember conversations, schedule autonomous tasks, evolve its skills, and operate across multiple platforms simultaneously.

Think of it as the TypeScript/Bun equivalent of Hermes Agent or DeerFlow, but designed for the JavaScript ecosystem with multi-platform support from day one.

Core Principles

| # | Principle | What it means | |---|-----------|---------------| | 1 | Zero-friction onboarding | One command install, guided setup, works immediately | | 2 | No vendor lock-in | Swap LLM providers with one config change | | 3 | Memory belongs to the user | Per-server scoping, privacy commands, GDPR-ready export | | 4 | Extensible without forking | Plugins, MCP servers, and skills — all hot-loadable | | 5 | Stability over features | Fewer features that work perfectly > many that break |

---

✨ Features

Platform & Provider

• Multi-platform — Discord, Telegram, REST API, CLI. Adding a new platform = one adapter file.
• Multi-provider LLM — OpenAI-compatible endpoints, Anthropic, Codex Responses, and AWS Bedrock via the provider adapter layer. Google/OpenRouter/Ollama are configured through compatible/custom endpoints where supported.
• Single shared worker — All transports share one engine instance. No duplicate processing.

Agent Capabilities

• Agentic tool-calling loop — Multi-step reasoning with self-correction (max 10+1 iterations).
• Built-in tools — get_time, web search/extract, checkpoint helpers, and local file/terminal tools when security policy allows them. Terminal execution is disabled by default.
• Tool policy and audit logs — Risk levels, workspace boundaries, secret redaction, and approval modes are implemented for local automation paths.
• Sandbox abstraction — Local and Docker backends exist for command execution; Docker isolation is minimal and should be reviewed before production use.
• MCP and plugins — MCP stdio/HTTP tool loading and plugin discovery are available for trusted local extensions.
• Skills manager — Built-in trigger skills still work, and local skills can be installed, enabled, disabled, audited, and removed from the CLI.

Memory & Persistence

• Full conversation persistence — User messages, assistant responses, tool calls, and tool results are saved to storage.
• Storage adapters — SQLite is the default. MySQL and Postgres adapters exist behind explicit config and require DATABASE_URL; MongoDB is planned only.
• Event/session tracking — Events and session metadata are persisted for audit and debugging.
• FTS5 search — SQLite full-text search is available for conversation history.
• Memory provider interface — The built-in provider wraps current memory behavior; a mock provider supports tests.
• Tiered retention — Auto-prune and archive settings exist, but review them before relying on them for compliance.

Experimental Autonomous Systems

• Cron scheduler — Core scheduling exists; verify delivery behavior on your transport before depending on it.
• Dream, goal, council, and free-will systems — Architecture exists, but these remain alpha features with incomplete product polish.
• Security engine — Risk classification, approval flow primitives, and audit records exist for tool execution.

Developer Experience

• TypeScript strict — Zero any types, noUncheckedIndexedAccess, JSDoc on every export.
• Bun tests — Unit + integration tests run with bun test; live provider tests are opt-in.
• Biome — Single linter/formatter, fast.
• config.yml — Human-readable YAML config (secrets stay in .env).
• Conventional commits — Structured git history with agent attribution.

---

🛠 Tech Stack

| Layer | Choice | Why | |-------|--------|-----| | Runtime | Bun ≥ 1.1 | 4× faster than Node.js, native SQLite, first-class TS | | Language | TypeScript (strict) | Zero any, full type safety | | Discord | discord.js v14 | Pure, aggressive cache disable (~5MB/guild) | | LLM | Custom provider abstraction | OpenAI-compatible, Anthropic, Codex Responses, and Bedrock adapters | | Storage | SQLite + adapter pattern | Zero-setup SQLite; MySQL/Postgres adapters are available when configured | | Config | YAML (config.yml) | Human-readable, comments, nested structure | | Linter | Biome | Single tool, fast, TS-aware | | License | Apache 2.0 | Permissive + patent grant |

---

🚀 Quickstart

Prerequisites

• Bun ≥ 1.1.0
• A Discord bot token (create one here)
• An LLM provider API key or a local Ollama instance

Setup

# 1. Clone
git clone https://github.com/fumino-development/fumino-engine.git
cd fumino-engine

# 2. Install dependencies
bun install

# 3. Create local config files
bun run src/cli.ts setup

# 4. Edit .env — add your secrets (Discord token, API keys)
# 5. Edit config.yml — set your provider, model, and preferences

# 6. Check local readiness without printing secrets
bun run src/cli.ts doctor

# 7. Register Discord slash commands when using Discord
bun run register-commands

# 8. Run
bun run dev

CLI Mode (no Discord needed)

bun src/cli.ts

---

🏗 Architecture

flowchart TD
    subgraph Main Thread
        Index[src/index.tsBoot Orchestrator]
        Hub[WorkerHubShared IPC Router]
        Discord[Discord Transport]
        Telegram[Telegram Transport]
        REST[REST API Transport]
        CLI[CLI Transport]
    end

    subgraph Worker Thread
        Engine[FuminoEngine15 Subsystems]
        Provider[LLM ProviderOpenAI / Anthropic / ...]
        Tools[Tool Registry11 built-in + MCP + plugins]
        Storage[(SQLite / MySQL / Postgres)]
    end

    Index --> Hub
    Hub --> Discord
    Hub --> Telegram
    Hub --> REST
    Index --> CLI

    Discord & Telegram & REST & CLI -->|IPC postMessage| Engine
    Engine --> Provider
    Engine --> Tools
    Engine --> Storage

Engine Subsystems (15)

| Subsystem | Purpose | Persisted | |-----------|---------|:---------:| | Agentic Loop | Multi-step tool calling with self-correction | — | | Context Builder | Token estimation + auto-compact | — | | Steering | Mid-processing user guidance | — | | Planning Agent | Task decomposition for complex requests | — | | Memory Facts | Auto-extract facts from conversations | ✅ | | Memory Evolver | Self-improving memory with decay | ✅ | | Soul System | Hot-reloadable personality (SOUL.md) | — | | Security Engine | Risk classification + audit log | ✅ | | Cron System | Scheduled autonomous tasks | ✅ | | Goal Engine | DAG-based task decomposition | ✅ | | Dream Processor | Idle-time memory consolidation | ✅ | | Skill Evolution | Fitness-based skill lifecycle | ✅ | | Session Tracker | Per-session metadata + cost | ✅ | | Event Logger | Append-only event sourcing | ✅ | | Retention Manager | Auto-prune + summarize + archive | ✅ |

---

⚙️ Configuration

Fumino uses a two-file config system:

| File | Contains | Example | |------|----------|---------| | .env | Secrets only (API keys, tokens, IDs) | DISCORD_TOKEN=xxx | | config.yml | All behavior settings | provider.model: gpt-4o-mini |

See [config.yml.example](./config.yml.example) for the full config reference.

Key settings:

provider:
  name: openai          # openai | anthropic | google | openrouter | ollama | custom
  model: gpt-4o-mini
  api_mode: auto

memory:
  default_scope: server # server | global | channel
  max_messages: 50

retention:
  auto_prune: true
  message_retention_days: 30
  event_retention_days: 90

---

🔌 Extensibility

Plugins

Drop a folder in plugins/ with plugin.json + index.ts. Auto-discovered at boot.

MCP Servers

Configure in config.yml:

mcp:
  servers:
    - name: my-tools
      transport: stdio
      command: npx -y @my/mcp-server

Skills

Drop a SKILL.md in skills// for trigger-based context injection, or use bun run src/cli.ts skills install to install a local skill with metadata tracking. Use bun run src/cli.ts skills audit before trusting third-party skills.

---

🚧 Development Status

Fumino Engine is in active alpha development. TypeScript and the default Bun test suite pass locally, but several product surfaces are still being hardened.

✅ Working Now

• Multi-platform chat (Discord, Telegram, REST, CLI)
• Multi-provider LLM adapter layer
• Agentic tool-calling loop with built-in and extension tools
• SQLite persistence for messages, events, sessions, and FTS5
• Config system (config.yml + .env secrets)
• Secure-by-default REST auth and OpenAI-compatible non-streaming endpoints
• CLI setup/doctor/model/tool/skill/memory command surfaces
• Tool policy gate, workspace jail checks, audit records, and checkpoint tools
• Slash commands (/memory, /steer, /skill, /compact)
• Plugin + MCP tool loading
• Shared worker architecture

🟡 Partially Working

• MySQL/Postgres storage adapters (implemented, lightly tested compared with SQLite)
• Docker sandbox backend (basic command construction and guardrails, not a hardened container runtime)
• Streaming responses (infrastructure exists; REST OpenAI-compatible streaming is planned)
• Cron, dream, skill evolution, council, and goal systems (alpha wiring)

🔴 Not Yet Implemented

• Web UI / Dashboard
• Voice/TTS
• Browser automation
• Hardened container sandboxing for untrusted code
• Full multi-agent orchestration UX (DeerFlow-style coordinator/planner/workers)
• WhatsApp transport
• OAuth / user authentication for REST API

Known Limitations

• Model-dependent behavior — Some models (gemma-4-31b-it) occasionally return empty responses on simple prompts. Retry logic mitigates this.
• Single-process only — No horizontal scaling yet. SQLite is the default (single-writer). MySQL/Postgres adapters exist but are lightly tested.
• No web UI — All interaction via Discord/Telegram/CLI/REST API for now.

---

📊 Project Stats

| Metric | Value | |--------|-------| | Commits | 75+ | | Tests | Run bun test locally for current count | | Source files | ~100 TypeScript | | Lines of code | ~15,000 | | Subsystems | 15 | | Built-in tools | See src/tools/builtin/ | | Transports | 4 | | Storage adapters | 3 (SQLite, MySQL, Postgres) | | any types | 0 |

---

🤝 Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a PR.

AI coding agents must additionally follow [AGENTS.md](./AGENTS.md) and [CLAUDE.md](./CLAUDE.md).

Local quality gates before committing:

bun run typecheck
bun run lint
bun test
bun run build

Use bun run format for formatting and bun run lint:fix for safe Biome-assisted cleanup.

Branch from master to feature/T-XXX- and use Conventional Commits.

---

💬 Community

Join the Fumino Development Group on Discord — discuss features, report bugs, share ideas, and get help.

[](https://discord.gg/bTxWhpXjzx)

👉 Join Discord Server

---

📜 License

Fumino Engine is licensed under the [Apache License, Version 2.0](./LICENSE).

Copyright © 2026 Rosela.

---

🙏 Acknowledgments

• Hermes Agent — inspiration for the dual-layer persistence architecture
• DeerFlow — inspiration for checkpoint concepts
• discord.js — Discord gateway library
• Anthropic — Model Context Protocol specification
• Bun — Making TypeScript runtime fast and fun
• Fumino Furuhashi (文乃) — whose diligence inspires this project's design philosophy

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fumino-development
• Source: fumino-development/fumino-engine
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.