Skip to content

README_EN.md

Latest commit

 

History

History
215 lines (157 loc) · 6.27 KB

README_EN.md

File metadata and controls

215 lines (157 loc) · 6.27 KB
Raw

🤖 Agentic-Desktop-Pet

Agentic-Desktop-Pet

English | 简体中文

👋 Introduction

🚀 🚀 🚀 Next-generation Agentic Desktop Pet = LLM + Memory + Emotion + RPG + Claude Code

Caution

Development is still in progress, there are many bugs, please be patient

🔀 Current Direction

The repo is now moving toward a safe gateway + OpenClaw agent architecture:

  • this project owns the public webhook/platform ingress
  • it performs signature verification, idempotency, moderation, routing, rate limiting, and event normalization
  • it writes shared soul/memory files directly into the OpenClaw workspace
  • only sanitized events are forwarded to OpenClaw
  • OpenClaw owns soul, memory, tool use, and character decisions

So this repo is better understood as a social ingress gateway rather than the final agent runtime.

✨ Features

🧠 Memory System (Cognee-based)

  • Knowledge Graph Memory: Organize conversations into semantic graphs using Cognee
  • Long-term Memory: Persistent storage across sessions
  • Semantic Search: Vector and graph search for memory retrieval
  • Memory Enrichment: Automatic entity and relationship extraction

💕 Dynamic Emotion System

  • Emotion States: Happy, sad, excited, bored, etc.
  • Time Decay: Emotions naturally decay over time
  • Interaction Boost: User interactions strengthen emotional bonds
  • Behavioral Influence: Emotion states affect Agent's response style

⚔️ RPG Attribute System

  • Base Attributes: Intelligence, charisma, agility, stamina, etc.
  • Experience & Level: Gain experience through conversations and tasks
  • Skill System: Unlock and upgrade abilities
  • Affinity: Emotional bond level with user

🛠️ Personal Assistant Capabilities

  • File Operations: Read, create, edit local files
  • Code Execution: Run code and scripts
  • Task Management: Create and manage todo items
  • System Integration: Execute commands and automation

🎨 Mod System

  • Easily add and switch between different desktop pet themes

🏗️ Architecture

Agentic-Desktop-Pet/
├── backend/                    # Python FastAPI Backend
│   ├── learn_agent/           # Agent Core Modules
│   │   ├── agent/             # Agent Implementation
│   │   │   ├── agent.py       # Main Agent Class
│   │   │   └── memory.py      # Memory Management
│   │   ├── memory/            # Memory System (Cognee)
│   │   │   └── cognee_manager.py
│   │   ├── emotion/           # Emotion System
│   │   │   └── emotion_engine.py
│   │   ├── rpg/               # RPG Attribute System
│   │   │   └── character.py
│   │   ├── llm/               # LLM Interface
│   │   └── tool/              # Tool Collection
│   │       ├── file_tool.py
│   │       ├── code_tool.py
│   │       └── todo_tool.py
│   ├── main.py                # FastAPI Entry Point
│   └── pyproject.toml
│
├── godot/                     # Godot 4.x Frontend
│   ├── scenes/               # Scene Files
│   ├── scripts/              # GDScript Scripts
│   ├── themes/               # Pet Themes
│   └── project.godot
│
├── docs/                     # Documentation
└── CLAUDE.md                # Claude Code Guide

🚀 Quick Start

Prerequisites

  • Python 3.13+
  • Godot 4.3+
  • LLM API (OpenAI / DeepSeek / Claude, etc.)

Install Backend

cd backend
uv sync

# Configure environment
cp .env.example .env
# Edit .env to add API Key

Start Service

# Start backend service
uv run main.py

# Service runs at http://localhost:8000

Run Frontend

  1. Open Godot 4.3+
  2. Import godot/ folder
  3. Click Run (or press F5)

Caution

Theme .pck files must be placed in the themes/ folder alongside the executable

📖 User Guide

⌨️ Shortcuts

  • Right-click on the pet to open the dialog
  • Press ESC to close the application when the pet window is focused

File Operations

"Read main.py for me"
"Create a new file hello.txt"
"Edit config.json"

Task Management

"Create a todo: buy milk"
"List my todos"
"Mark the first todo as done"

Check Status

"How are you feeling?"
"How much experience do you have?"
"Show me your attributes"

Instagram Gateway

The backend now includes an Instagram gateway:

  • GET /webhook/instagram: Meta webhook verification
  • POST /webhook/instagram: inbound Instagram comment events
  • GET /gateway/health: gateway health status

Before any event reaches OpenClaw, the gateway performs:

  • signature verification
  • simple keyword moderation
  • per-user rate limiting
  • duplicate event filtering
  • normalized event packaging

🛣️ Roadmap

See TODO.md

🐶 Build Your Own Desktop Pet

Wiki Tutorial

🤝 Contributing

The project is currently in development (updates when time permits), and there are still many bugs being fixed. Contributions of any size are welcome - whether it's fixing bugs, adding character assets, or other improvements.

©️ License

You may use any code snippets from this project, but you cannot directly package the complete project for commercial use. Please also respect the copyright of assets used in the project.

🙏 Acknowledgements