Psycheros

A persistent AI entity — not a chat thread, not an assistant framework.

Quickstart with the launcher Source on GitHub

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 handles install, update, start, and stop. Pick your platform:

macOS / Linux

Download install.sh.
Run it:
Terminal window
```
bash install.sh
```

Windows

Download install.ps1.
Right-click → Run with PowerShell.

If PowerShell refuses unsigned scripts, allow them once with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Full reference and troubleshooting: Launcher user guide.

What’s in the box

Launcher Start here. Two-file installer + dashboard that handles install / update / start / stop for non-technical operators.

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.