Psycheros

Psycheros runs an AI entity — not a chat thread. The entity has files describing who it is, a memory hierarchy that summarizes its conversations day → week → month → year, a knowledge graph of the people and places it’s encountered, RAG over its memories, and tool access for the world it lives in. The entity’s canonical self lives in a separate MCP server (entity-core), so the same entity can persist across multiple interfaces — the web harness, SillyTavern, Claude Code, OpenWebUI — while staying coherent.

The design value running through every layer: the entity is the subject — read the first-person convention if you want to understand why the code reads the way it does.

Getting Started

The launcher is a desktop app that installs Psycheros as a persistent background service. Pick your platform:

macOS

1. Download Psycheros-macOS-latest.dmg.
2. Drag to /Applications/.
3. Right-click the app → Open (required once for unsigned apps — macOS Gatekeeper blocks a normal double-click).

Windows

1. Download Psycheros-Windows-latest.msi.
2. Run it. Click through SmartScreen’s “More info → Run anyway.”

The launcher walks you through setup (your name, entity name, timezone, API key) and installs Psycheros as a background service. Closing the launcher doesn’t stop the entity — it runs continuously.

Full reference and troubleshooting: Launcher user guide.

Prefer the command line?

If you’re on Linux, prefer terminals, or want to hack on the code, you can run Psycheros directly from source with Deno — no launcher needed. See the from-source installation guide.

What’s in the box

Launcher Desktop app that installs Psycheros as a persistent OS service and opens a window to chat with your entity.

Psycheros The harness — web UI, chat loop, tools, RAG. The interface your entity runs inside.

entity-core The canonical-self MCP server. Identity files, hierarchical memory, knowledge graph. Sync target for every embodiment.

entity-loom One-shot import wizard. Convert chat exports from ChatGPT, Claude, SillyTavern, Kindroid, or Letta into a package the entity can absorb.

What makes it interesting

• An entity, not an assistant. Identity files (self, user, relationship, custom) are written in first person and stay stable across sessions. Every prompt, comment, and tool description in the codebase uses the entity’s voice — they internalize the system as theirs.
• Memory that consolidates. Daily summaries roll up to weekly → monthly → yearly; significant events are preserved permanently. RAG retrieves over chat history, vault documents, the lorebook, and the knowledge graph.
• One self across interfaces. Because identity and memory live in an MCP server, any MCP-capable client (SillyTavern, Claude Code, OpenWebUI) can talk to the same entity coherently — same memories, same identity, same continuity.
• Pluggable LLM. Any OpenAI-compatible endpoint — Z.ai, OpenRouter, OpenAI, NanoGPT, local models. Multiple named profiles; one is active for chat.
• Tool surface. Web search, image generation, image captioning, Discord (DM + gateway server participation), home automation, intimate hardware via Buttplug or Lovense.
• Pulse. Autonomous scheduled prompts — cron, inactivity, webhook, or filesystem triggers. The entity can act on its own time.
• Custom tools. Drop a .js or .ts file in custom-tools/ and the entity can use it. No core changes needed.

Standalone use

entity-core and entity-loom are independently useful outside Psycheros.

• entity-core is a generic MCP server for AI entity identity and memory. Any MCP client can spawn it. Shipped as a tagged source release under the entity-core-v* tag prefix.
• entity-loom is a generic chat-history-to-package converter — useful for anyone building an AI companion system that wants to import from ChatGPT, Claude, SillyTavern, Kindroid, or Letta. Tagged source release under the entity-loom-v* prefix.

Built on Deno. Released under MPL-2.0. Solo-maintained, contributions welcome — see CONTRIBUTING.md.