# Fumino Engine

> Where knowledge flows, voices follow.

- **Type:** MCP server
- **Install:** `agentstack add mcp-fumino-development-fumino-engine`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fumino-development](https://agentstack.voostack.com/s/fumino-development)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [fumino-development](https://github.com/fumino-development)
- **Source:** https://github.com/fumino-development/fumino-engine

## Install

```sh
agentstack add mcp-fumino-development-fumino-engine
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/NousResearch/hermes-agent) (Python) or [LangGraph](https://github.com/langchain-ai/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](https://github.com/NousResearch/hermes-agent) or [DeerFlow](https://github.com/bytedance/deer-flow), 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](https://bun.sh) ≥ 1.1 | 4× faster than Node.js, native SQLite, first-class TS |
| Language | TypeScript (strict) | Zero `any`, full type safety |
| Discord | [discord.js v14](https://discord.js.org) | 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](https://biomejs.dev) | Single tool, fast, TS-aware |
| License | Apache 2.0 | Permissive + patent grant |

---

## 🚀 Quickstart

### Prerequisites

- [Bun](https://bun.sh) ≥ 1.1.0
- A Discord bot token ([create one here](https://discord.com/developers/applications))
- An LLM provider API key **or** a local Ollama instance

### Setup

```bash
# 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)

```bash
bun src/cli.ts
```

---

## 🏗 Architecture

```mermaid
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:

```yaml
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`:
```yaml
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:

```bash
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](https://www.conventionalcommits.org/).

---

## 💬 Community

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

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

👉 **[Join Discord Server](https://discord.gg/bTxWhpXjzx)**

  

---

## 📜 License

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

Copyright © 2026 Rosela.

---

## 🙏 Acknowledgments

- [Hermes Agent](https://github.com/NousResearch/hermes-agent) — inspiration for the dual-layer persistence architecture
- [DeerFlow](https://github.com/bytedance/deer-flow) — inspiration for checkpoint concepts
- [discord.js](https://discord.js.org) — Discord gateway library
- [Anthropic](https://www.anthropic.com/) — Model Context Protocol specification
- [Bun](https://bun.sh) — 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](https://github.com/fumino-development)
- **Source:** [fumino-development/fumino-engine](https://github.com/fumino-development/fumino-engine)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-fumino-development-fumino-engine
- Seller: https://agentstack.voostack.com/s/fumino-development
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.