Metadata-Version: 2.4
Name: kynetic-agents
Version: 0.5.1
Summary: Multi-agent Discord runtime for hub-and-spoke AI teams — forked from kynetic-agents
Project-URL: Homepage, https://github.com/kynetic-ai/kynetic-agents
Author-email: "Miguel Alonso Jr." <miguel@kynetic.ai>
Maintainer-email: "Miguel Alonso Jr." <miguel@kynetic.ai>
License: MIT License
        
        Copyright (c) 2026 Tim Kellogg
        Copyright (c) 2026 Miguel Alonso Jr.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.12.15
Requires-Dist: apscheduler>=3.11.2
Requires-Dist: deepagents>=0.4.1
Requires-Dist: discord-py>=2.6.4
Requires-Dist: matplotlib>=3.8
Requires-Dist: mcp>=1.26.0
Requires-Dist: mempalace
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: pyyaml>=6.0.3
Description-Content-Type: text/markdown

# kynetic-agents

> **Forked from [open-strix](https://github.com/open-strix/open-strix).** This project extends open-strix with first-class support for multi-agent interaction via Discord using a **hub-and-spoke topology**: a central hub agent coordinates a fleet of spoke agents, each living in its own Discord channel, communicating through mentions and configurable `home_channels` routing.

[![PyPI version](https://img.shields.io/pypi/v/kynetic-agents.svg)](https://pypi.org/project/kynetic-agents/)

A persistent AI companion framework that lives in Discord, remembers everything, and gets better over time. Designed for running multiple agents together.

```bash
uvx kynetic-agents setup --home my-agent --github
cd my-agent
uv run kynetic-agents
```

Two commands. You have an agent. Connect it to Discord and start talking.

## What is this?

kynetic-agents is an opinionated framework for building long-running AI agents. Not chatbots — *companions*. Agents that develop personality through conversation, maintain memory across sessions, schedule their own work, and learn from their mistakes.

It runs on cheap models (MiniMax M2.5, ~$0.01/message), talks to you over Discord, and stores everything in git. No vector databases, no cloud services, no enterprise pricing. Just files, memory blocks, and a git history you can actually read.

**Hub-and-spoke multi-agent topology:** Each agent owns one or more Discord channels (`home_channels`). A hub agent coordinates the fleet — spokes communicate back to the hub by @mentioning it in their own channels. The hub has read access to spoke channels and picks up those messages automatically.

**How you interact with it:** You talk to agents on Discord. They talk back using tools (`send_message`, `react`). They have scheduled jobs that fire even when you're not around. Over time, they develop interests, track your projects, and start doing useful things without being asked.

## Why this exists

Most agent frameworks optimize for tool-calling pipelines or enterprise orchestration. kynetic-agents optimizes for a different thing: **agents that know you and get better over time**, and that can work together without getting in each other's way.

Three design bets:

- **Focused.** Small core, everything else is skills — markdown files the agent reads and follows. Add capabilities by dropping a file in `skills/`, or let the agent discover and install them at runtime.
- **Cheap.** Defaults to MiniMax M2.5 via the Anthropic-compatible API. Pennies per message. Run it on a $5/month VPS.
- **Stable.** Ships with built-in skills for self-diagnosis — prediction calibration loops, event introspection, onboarding that fades into regular operation. The agent can read its own logs, check whether its predictions were right, and notice when it's drifting.

## How it works

### The home repo

When you run `uvx kynetic-agents setup`, it creates a directory — the agent's *home*. Everything the agent knows lives here:

```
blocks/          # YAML memory blocks — identity, goals, patterns. In every prompt.
state/           # Markdown files — projects, notes, research. Read on demand.
skills/          # Markdown skill files. Drop one in, agent picks it up.
logs/
  events.jsonl   # Every tool call, error, and event. The agent can read this.
  chat-history.jsonl # Append-only chat transcript.
  journal.jsonl  # Agent's own log — what happened, what it predicted.
scheduler.yaml   # Cron jobs the agent manages itself.
config.yaml      # Model, Discord config, prompt tuning.
```

Everything except logs is committed to git after every turn. The git history *is* the audit trail.

### Multi-agent routing with `home_channels`

Each agent can be configured with a list of channels it should respond in:

```yaml
home_channels:
  - my-agent-channel
  - 1234567890123456789   # channel IDs also work
```

When `home_channels` is set, the agent only processes messages in those channels — unless it is directly @mentioned or an `always_respond_bot_ids` bot explicitly addresses it by name or ID. When `home_channels` is empty, the agent responds in all channels (original behavior).

For hub-and-spoke deployments:
- Give each spoke agent its own `home_channels` entry
- The hub agent reads all spoke channels (via Discord permissions) and picks up spoke→hub messages via `@mention`
- Spokes communicate to the hub through their `collaboration.md` onboarding docs

### Memory

Two layers:

- **Blocks** (`blocks/*.yaml`) — short text that appears in every prompt. Identity, communication style, current focus, relationships.
- **Files** (`state/`) — longer content the agent reads when relevant. Research notes, project tracking, world context.

No embeddings, no vector search. Just files and git.

#### Shared semantic memory with mempalace

For multi-agent deployments, agents can share a common semantic memory store backed by [mempalace](https://github.com/mempalace/mempalace). This allows any agent to semantically search the conversation history of a shared channel — retrieving relevant past messages without knowing which file to read.

**Architecture:** One designated process runs the writer (a singleton background coroutine that ingests messages into the palace). All other processes connect to the same store as read-only clients. This prevents write contention across processes.

**Config fields:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `mempalace_path` | string | Yes, if using mempalace | Absolute path to the shared palace directory. Must be the same path across all processes. |
| `mempalace_channels` | list of strings | Yes, if using mempalace | Channels to monitor and expose for search. Accepts channel IDs or names (same format as `home_channels`). |
| `mempalace_writer` | bool | No (default: `false`) | Set to `true` in exactly one process. That process runs the writer coroutine that ingests messages into the palace. All other processes are read-only. |

**Writer process** (`config.yaml`):
```yaml
mempalace_path: /shared/palace
mempalace_writer: true
mempalace_channels:
  - "1234567890123456789"   # channel ID
  - general                 # or channel name
```

**All other processes** (`config.yaml`):
```yaml
mempalace_path: /shared/palace
mempalace_channels:
  - "1234567890123456789"
  - general
```

When `mempalace_path` is set, agents automatically receive six read-only search tools: `mempalace_search`, `mempalace_get_drawer`, `mempalace_kg_query`, `mempalace_kg_timeline`, `mempalace_get_taxonomy`, and `mempalace_list_drawers`. Write tools are never exposed to agents.

Only new messages are written to the palace — chat history replayed from disk on restart is not re-ingested.

### Skills

A skill is a markdown file in `skills/` with a YAML header. The agent sees all skills in its prompt and invokes them by name.

```yaml
---
name: my-skill
description: What this skill does and when to use it.
---
# Instructions for the agent
...
```

Built-in skills:

| Skill | Purpose |
|-------|---------|
| **onboarding** | Walks the agent through establishing identity, goals, and schedules |
| **memory** | How to maintain and organize memory blocks and state files |
| **skill-creator** | Create new skills from repeated workflows |
| **prediction-review** | Calibration loops — revisit past predictions against ground truth |
| **introspection** | Self-diagnosis from event logs and behavioral patterns |
| **five-whys** | Root-cause analysis when predictions or behaviors go wrong |

### Scheduling

The agent has tools to create, modify, and remove its own scheduled jobs. Jobs are cron expressions stored in `scheduler.yaml`. When a job fires, it sends a prompt to the agent — even if no human is around.

### Events API

Every tool call, incoming message, error, and scheduler trigger is logged to `logs/events.jsonl`. The agent can read its own event log — and the introspection skill teaches it how.

When `api_port` is set in `config.yaml`, a loopback REST API accepts events from external scripts.

## Setup

Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) and a Discord bot token.

```bash
uvx kynetic-agents setup --home my-agent --github
cd my-agent
# Edit .env with your API key and DISCORD_TOKEN
uv run kynetic-agents
```

The setup command handles everything: directory structure, git init, GitHub repo creation (with `--github`), service files for your OS, and a walkthrough for model/Discord configuration.

See [SETUP.md](SETUP.md) for detailed instructions on environment variables, model configuration, Discord setup, and deployment options.

## Upgrading

```bash
uv add -U kynetic-agents
```

## Configuration

`config.yaml`:

```yaml
model: MiniMax-M2.5
model_max_retries: 6
journal_entries_in_prompt: 90
discord_messages_in_prompt: 10
discord_token_env: DISCORD_TOKEN
always_respond_bot_ids: []
home_channels: []
api_port: 0

# Shared semantic memory (optional — see Memory section)
mempalace_path: /shared/palace
mempalace_writer: false
mempalace_channels: []
```

Models use the Anthropic-compatible API format. MiniMax M2.5 and Kimi K2.5 both work out of the box. Any model with an Anthropic-compatible endpoint will work — set `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY` in `.env`.

## Tests

```bash
uv run pytest -q
```

## Safety

Agent file writes are limited to `state/` and `skills/`. Reads use repository scope. Built-in skills are read-only.

There is no sandboxing. Agents have full shell access. This is intentionally simple and should not be treated as a security boundary.

## License

MIT. See `LICENSE`.
