Muninnai

English | 中文

---

English

Introduction

Muninnai is a proactive AI companion agent built with Java 17 and Spring Boot. Unlike traditional chatbots that only respond when prompted, Muninnai can autonomously initiate conversations based on an energy-driven model, making it a truly proactive digital companion.

further with a sophisticated memory system, vector-based semantic retrieval, and multi-channel support.

Key Features

Feature	Description
Proactive Conversations	Energy model + LLM judge enable the agent to initiate conversations autonomously
5-Layer Memory System	MEMORY / SELF / PENDING / HISTORY / RECENT_CONTEXT -- structured Markdown-based memory with consolidation
Vector Memory	Elasticsearch + DashScope embeddings with HyDE enhancement for semantic retrieval
ReAct Reasoning	Tool-augmented reasoning loop with graceful context-length fallback
Multi-Channel	Feishu/Lark, Telegram, CLI, QQ (extensible channel interface)
Tool System	Built-in tools (file I/O, shell, web fetch, Feishu docs) with lifecycle hooks
Skill System	Markdown-based skill definitions loaded from workspace

Tech Stack

Layer	Technology
Framework	Spring Boot 3.3.5
Language	Java 17
LLM	Spring AI 1.0.3 (DeepSeek + DashScope)
Vector Store	Elasticsearch 9.x
Database	MySQL 9.5 (Druid)
Build	Maven

Getting Started

Prerequisites: Java 17+, MySQL, Elasticsearch

# Clone the repository
git clone https://github.com/lokidundun/Muninnai.git
cd Muninnai

# Configure
# Edit src/main/resources/application.yml with your database, LLM API keys, and channel tokens

# Build
mvn clean package

# Run
java -jar target/Muninnai-0.1.0-SNAPSHOT.jar

The application starts on port 9191.

Configuration

Edit src/main/resources/application.yml:

spring:
  ai:
    deepseek:
      api-key: sk-xxx            # DeepSeek API Key
    openai:
      api-key: sk-xxx            # DashScope API Key (for embeddings)
  datasource:
    url: jdbc:mysql://localhost:3306/muninnai
    username: root
    password: your_password
  elasticsearch:
    uris: http://localhost:9200

loki:
  agent:
    proactive:
      default-session: feishu:your_chat_id   # format: channel:chatId
                                              # e.g. feishu:oc_xxx, cli:console
    feishu:
      enabled: true
      app-id: cli_xxx
      app-secret: xxx
      verification-token: xxx

Field	Description
spring.ai.deepseek.api-key	DeepSeek API key for chat
spring.ai.openai.api-key	DashScope API key for embeddings
spring.datasource.*	MySQL connection (database auto-created)
spring.elasticsearch.uris	Elasticsearch endpoint
default-session	Where proactive messages are sent. Format: channel:chatId
loki.agent.feishu.*	Feishu bot credentials (Feishu Open Platform)

Architecture

Muninnai
├── Agent Core          -- Passive turn pipeline + ReAct reasoning loop
├── Memory System       -- 5-layer Markdown memory + vector retrieval
├── Proactive System    -- Energy model, judge, sensor, drift mode
├── Channel Layer       -- Feishu / Telegram / CLI / QQ abstraction
├── Tool System         -- Extensible tool framework with hooks
└── Skill System        -- Markdown-defined skill loader

System Architecture

Passive Turn Pipeline

Star History ✨

License

MIT