# muiwolf

**Repository Path**: Sunleader/muiwolf

## Basic Information

- **Project Name**: muiwolf
- **Description**: 使用 neo4j + embedding 为 agent 提供记忆能力
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-17
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MuiWolf

An AI-driven intelligent assistant system with a Spring Boot backend and Next.js frontend.

## Architecture

```
┌─────────────────┐      WebSocket       ┌─────────────────┐
│   wolf-chat     │ ────────────────────── │   WolfAgent     │
│   (Next.js)     │                        │  (Spring Boot)  │
│   localhost     │                        │   localhost     │
│   :3000         │                        │   :8080         │
└─────────────────┘                        └────────┬────────┘
                                                     │
                    ┌────────────────────────────────┼────────────────────────────────┐
                    │                                │                                │
                    ▼                                ▼                                ▼
            ┌───────────────┐               ┌───────────────┐                ┌───────────────┐
            │   Neo4j       │               │   AlphaAgent  │                │   AlphaTool   │
            │ (Vector Store)│               │  (AI Brain)   │                │  (HTTP Server)│
            └───────────────┘               └───────────────┘                └───────────────┘
```

## Tech Stack

### Backend - WolfAgent

| Component | Technology |
|-----------|------------|
| Framework | Spring Boot 3.5.11 |
| Language | Java 17 |
| AI | Spring AI 1.1.2 (MiniMax / OpenAI compatible) |
| Vector Store | Neo4j |
| WebSocket | Spring WebSocket |
| HTTP Server | Netty |

### Frontend - wolf-chat

| Component | Technology |
|-----------|------------|
| Framework | Next.js 16.2.0 (App Router) |
| Language | TypeScript |
| UI | React 19 + Tailwind CSS 4 |

## Features

- **AI Agent** - LLM-powered conversational agent with tool calling
- **Vector Memory** - Neo4j-backed persistent memory with embedding-based recall
- **Tool System** - Extensible tool calling (terminal, memory, HTTP)
- **WebSocket Communication** - Real-time bidirectional messaging
- **Workspace Management** - Persistent workspace at `~/.alpha`

## Project Structure

```
muiwolf/
├── WolfAgent/                    # Spring Boot backend
│   ├── src/main/java/
│   │   └── io/github/sunleader1997/muiwolf/wolfagent/
│   │       ├── WolfAgentApplication.java
│   │       ├── base/
│   │       │   ├── BaseAgent.java        # Abstract agent with chat memory & tools
│   │       │   └── AlphaAgent.java       # Main singleton agent implementation
│   │       ├── config/
│   │       │   ├── AlphaAgent.java       # Configuration properties
│   │       │   ├── Neo4jConfig.java       # Neo4j vector store config
│   │       │   └── WolfToolCallingManager.java
│   │       ├── service/
│   │       │   └── AlphaAgentService.java # WebSocket session & conversation
│   │       ├── websocket/
│   │       │   └── ChatWebSocketHandler.java
│   │       └── tools/
│   │           ├── MemoryTool.java        # Vector memory recall/save
│   │           ├── TerminalTool.java      # Command execution
│   │           └── AlphaTool.java         # HTTP server (Netty)
│   └── src/main/resources/
│       ├── application.yml
│       └── prompt/alpha_agent_system_prompt.md
│
└── wolf-chat/                     # Next.js frontend
    ├── src/
    │   ├── app/page.tsx          # Main chat UI
    │   ├── hooks/useWebSocket.ts # WebSocket connection
    │   ├── components/
    │   │   ├── ChatMessageList.tsx
    │   │   └── ChatInput.tsx
    │   └── types/chat.ts
    └── package.json
```

## Getting Started

### Prerequisites

- Java 17+
- Node.js 20+
- Maven 3.8+
- Neo4j (for vector memory)

### Backend Setup

```bash
cd WolfAgent

# Set environment variables
export MINIMAX_API_KEY=your_api_key

# Run with Maven wrapper
./mvnw spring-boot:run

# Or build and run
./mvnw clean package
java -jar target/WolfAgent-0.0.1-SNAPSHOT.jar
```

The backend starts on `http://localhost:8080`.

### Frontend Setup

```bash
cd wolf-chat

# Install dependencies
npm install

# Run development server
npm run dev
```

The frontend starts on `http://localhost:3000`.

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `MINIMAX_API_KEY` | MiniMax API key for chat and embeddings | Yes |
| `OPENAI_API_KEY` | OpenAI API key (alternative) | No |

### Neo4j Configuration

Edit `WolfAgent/src/main/resources/application.yml`:

```yaml
wolf:
  neo4j:
    enable: true
    model: embedding
    remote:
      url: bolt://127.0.0.1:7687
      username: neo4j
      password: your_password
```

## Agent Tools

| Tool | Description |
|------|-------------|
| `MemoryTool` | Save and recall memories using vector embeddings |
| `TerminalTool` | Execute shell commands |
| `AlphaTool` | HTTP server for external triggers |

## WebSocket API

Connect to `ws://localhost:8080/ws/chat`

### Send Message
```json
{
  "type": "chat",
  "content": "Hello Alpha",
  "sessionId": "user-session-id"
}
```

### Receive Response
```json
{
  "type": "result",
  "content": "Hello! I'm Alpha.",
  "sessionId": "user-session-id"
}
```

## License

MIT