PulseFlake💕

PulseFlake (formerly FuckingLonely) is a decentralized, Event-Driven Reactive AI ecosystem. It is designed to bridge Multi-Modal Large Language Models (MLLM) with real-world applications through a high-performance Unix Socket IPC layer.

By decoupling the AI "brain" from its "sensors" and "tools," PulseFlake enables modular, scalable, and highly reactive autonomous agents that can process multi-modal events and orchestrate complex tool-driven workflows.

🏗️ Technical Architecture

PulseFlake is built on a modular, event-driven architecture using Unix Socket IPC for high-performance communication between independent processes.

The Core Philosophy: "Everything is a Socket"

At its most abstract, the system consists of three fundamental primitives:

1. The Bus (UnixSocket.js): A lightweight wrapper around Node's net module that allows any process to act as both a Server (listening for requests) and a Client (sending requests/broadcasts) over Unix domain sockets.
2. The Provider (BaseProvider.js): A generic interface for "Intelligence." It doesn't care if the intelligence comes from Gemini, Llama, or a set of hardcoded rules. It translates multi-modal inputs into structured tool calls and text responses.
3. The Registry (apps/tools): A central process that keeps track of which socket "owns" which capability.

Abstract Workflow

sequenceDiagram
    participant App A (Requester)
    participant Bus (Unix Sockets)
    participant Registry (Tools)
    participant App B (Provider)

    Note over App B: 1. Initialization
    App B->>Bus: Create socket 'app-b.sock'
    App B->>Registry: Register "Tool X" via Bus

    Note over App A: 2. Discovery & Execution
    App A->>Registry: "Who can do Tool X?"
    Registry-->>App A: "App B can"
    App A->>Bus: Request 'Tool X' from 'app-b.sock'
    Bus->>App B: Incoming Request
    App B-->>Bus: Response Data
    Bus-->>App A: Final Result

Loading

The "Generic" Micro-App Pattern

Every micro-app follows a standard lifecycle enabled by the UnixSocket utility:

1. Identity: Each app creates a new UnixSocket("app-name").
2. Registration: On startup, it connects to a discovery socket (usually tools.sock) and sends its JSON schema.
3. Interface: It uses server.listen('*', 'method', callback) to wait for incoming instructions.
4. Decoupling: No app needs to know the physical location or implementation details of another. They only need to know the Method Name and the Socket Identifier.

---

📖 The Story of PulseFlake

The project began as a personal endeavor to bridge the gap between AI and daily digital life, evolving through several stages of architectural complexity.

The Evolution

• V1: The Beginning (June 2025)
  Originally titled FuckingLonely, this version focused on creating a unified AI assistant that could monitor Discord and manage basic memories. It was a monolithic structure that set the foundation for context awareness and basic tool use.

• V2: Refined Core (Late 2025)
  The project shifted towards a "Character" based system, introducing more modular modules like api-monitor.js and early scraping attempts. It was here that the modular philosophy began to take root.

• V3 & V4: The Bus & Apps (Early 2026)
  Version 3 introduced the concept of a "Bus" for inter-process communication. By Version 4, the system started splitting into specialized folders for ai, discord, internet, and system tasks, moving away from a single script.

• V5: The Final Prototype (March 2026)
  V5 refined the provider system (supporting various Gemini models) and perfected the scraper logic (like the University portal). It was the most stable version before the current transition to the PulseFlake architecture.

• PulseFlake💕 (Current)
  The latest evolution. A fully decentralized micro-app ecosystem where the Agent and Tools are distinct services, communicating via specialized Unix Sockets for maximum flexibility and performance.

---

🏛️ Architecture Overview

The system is designed around a "Manager-Worker" pattern where all apps are equals but fulfill specific roles:

1. The Agent (apps/agent): The central logic engine. It receives events from other apps and uses Gemini 3.1 Flash (Lite) to decide which tools to invoke.
2. The Tools Registry (apps/tools): A RAG-powered (Retrieval-Augmented Generation) lookup service. Apps register their "function definitions" here, and the Agent searches for them on-demand.
3. The Apps (apps/*): Specialized modules that either provide input (Events) or perform actions (Tools).

---

📱 Current Apps

App	Description
Agent 🤖	The brain. Processes incoming events and determines the best course of action using tool-calling. Supports recursive multi-agent orchestration and memory management.
Calendar 📅	Full-featured event management system. Supports recurring events (daily, weekly, workdays, weekend, monthly, yearly, custom), conflict detection, reminders, timelines, and timezone support.
Console 🎛️	Enhanced web-based GUI to monitor active services, manually trigger tools, and chat with the Agent. Features real-time event monitoring and tool exploration.
Device 🖥️	System device integration for command execution, file operations, and remote connection handling.
Discord 💬	A bridge between Discord channels/DMs and the Agent. Supports message handling, reactions, and event broadcasting.
Imagen 🎨	Image generation tool using Pollinations AI. Generates images based on natural language prompts.
Internet 🌐	Provides web search and content retrieval capabilities to the Agent.
Tools 🔧	The system registry where all available tool definitions are indexed using vector embeddings.
University 🏛️	Scraper for the UAJY student portal. Supports login, fetching courses, tasks, and content.
WhatsApp 📱	A bridge for WhatsApp Messenger. Supports reading chats, sending messages, note management, and chat summarization.
Template 📂	A boilerplate for quickly spinning up new PulseFlake micro-apps.

---

🎯 Generic Use Case: Multi-Agent Orchestration

PulseFlake supports Recursive Multi-Agent Orchestration. The main Agent can spawn Sub-Agents to handle complex, long-running, or isolated sub-tasks.

Sub-Agent Workflow

1. Spawn: The Main Agent calls agent.spawnSubagent({ goal: "Task description" }).
2. Isolation: The Sub-Agent receives the goal and its own tool-calling loop. It does not hear global system events, ensuring focus.
3. Recursive: Sub-Agents can spawn their own nested Sub-Agents if a task needs further decomposition.
4. Reporting: Once finished, the Sub-Agent uses the agent.done({ message: "Result" }) tool to report back to its parent and terminate.

---

🚀 Getting Started

1. Clone & Install: npm install
2. Environment Setup: Create a .env file with your GEMINI_API_KEYS.
3. Launch the System: Run individual apps (e.g., node apps/agent/index.js, node apps/discord/index.js, etc.).
4. Interact: Use the Discord bridge or the Console to begin interacting with the Agent.

---

🛡️ License

MIT License. Designed with ❤️ for the future of decentralized AI.

PulseFlake is designed to solve the problem of disconnected digital tools. In most systems, your Calendar, your Chat, and your Code projects don't talk to each other. PulseFlake bridges them using the Generic Tool Pattern.

The Real-World Problem

Imagine you are working on a code project and a critical bug is reported in your Discord. You need to:

1. Check the error logs.
2. Search documentation for a fix.
3. Deploy a patch.
4. Update the user on Discord.

Normally, this requires manual switching between 4-5 different apps.

The PulseFlake Solution (The "Flow")

Because PulseFlake uses a Decoupled Architecture, you can add any tool without rebuilding the core:

1. Event Reception: A Monitoring App listens for errors and broadcasts an event to the Agent.
2. Autonomous Decision: The Agent queries the Tools Registry for a "Search" tool and "File Reader" tool.
3. Cross-Socket Execution:
   • The Agent calls the Filesystem App to read the log files.
   • It calls the Internet App to search for the specific error signature.
   • It generates a summary and sends it back to the Discord App.
4. Action Persistence: Every step is recorded in a shared Memory layer, so the Agent "remembers" it already tried searching for that specific bug.

Core Implementation Pattern

To implement any real-world solution, you only need to follow this pattern:

• Define the Capability: Create a JSON schema for your tool (e.g., execute_ssh_command).
• Expose the Socket: Use UnixSocket.js to listen for that capability name.
• Register & Forget: Once registered in the Tools Registry, the Agent will automatically discover and use your tool whenever the context requires it.

---

⚡ Quick Start

1. Installation

git clone https://github.com/Neuxbane/PulseFlake.git
cd PulseFlake
npm install

2. Environment Setup

Create a .env file in the root with your API keys:

GEMINI_API_KEYS=your_key1,your_key2
DISCORD_TOKEN=your_token

3. Running the Ecosystem

It is recommended to run each service in its own screen or pm2 process.

Base system:

node apps/tools/index.js      # Required first (Registry)
node apps/agent/index.js      # Required second (Brain)

Feature modules:

node apps/discord/index.js
node apps/university/index.js
node apps/internet/index.js
node apps/calendar/index.js
node apps/device/index.js

---

📅 Calendar Features

The Calendar app provides comprehensive event management with advanced scheduling capabilities:

Core Features

• Event Management: Create, read, update, and delete calendar events.
• Recurring Events: Support for multiple recurrence patterns:
  • Built-in: daily, weekly, workdays, weekend, monthly, yearly
  • Custom: Function-based rules like (curr, evnt) => curr.day == evnt.day
• Conflict Detection: Prevents overlapping events based on event importance and parallelability.
• Reminders: Set multiple reminder times (in seconds) before events trigger notifications to the Agent.
• Timeline View: Fetch upcoming events with automatic processing of recurring patterns.
• Timezone Awareness: Automatic detection and handling of system timezone.

Event Properties

{
  title: string,                   // Event name (required)
  description: string,             // Markdown description
  start: ISO8601,                  // Event start date/time
  duration: number,                // Duration in minutes
  repeat: string,                  // Recurrence rule
  parallelable: boolean,           // Can overlap with other events (default: true)
  important: boolean,              // Mark as important (default: true)
  reminds: number[],               // Reminder times in seconds before event
  attachments: object[],           // URLs, images, or files
  tags: string[]                   // Event categorization
}

Available Tools

• createEvent: Create new calendar events with conflict checking.
• listEvents: Retrieve all raw event data.
• updateEvent: Modify existing events.
• deleteEvent: Remove events from the calendar.
• timeline: Get upcoming events (automatically expands recurring patterns).
• getUpcomingReminders: Fetch events with scheduled reminders.

---

🛠️ Development & Contributions

PulseFlake is built to be extended. Whether you want to add new capabilities or support new AI models, follow the guides below:

• Making New Apps: Learn how to create micro-apps that register tools and broadcast events.
• Adding AI Providers: Guide on extending the BaseProvider to support LLMs like OpenAI, Anthropic, or local Ollama instances.

---

📜 Technical Details

• Communication: JSON-delimited line messages over Unix Domain Sockets (.sock).
• Provider: Gemini 3.1 Flash (Lite/Preview) for thinking and embedding.
• Discovery: Semantic search (cosine similarity) allows the Agent to find tools even if if doesn't know their exact names.

---

Made with love (and sockets). 🧠💕