{"id":49813884,"url":"https://github.com/psycherosai/psycheros","last_synced_at":"2026-06-28T01:01:27.289Z","repository":{"id":357486162,"uuid":"1235557096","full_name":"PsycherosAI/Psycheros","owner":"PsycherosAI","description":"A persistent AI entity harness. The entity has its own identity files, a memory hierarchy that consolidates across time, and a single canonical self that persists across multiple interfaces.","archived":false,"fork":false,"pushed_at":"2026-06-26T00:55:30.000Z","size":4002,"stargazers_count":22,"open_issues_count":21,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-26T02:14:53.697Z","etag":null,"topics":["ai-agent","ai-companion","ai-entity","ai-harness","ai-memory-system","deno"],"latest_commit_sha":null,"homepage":"https://psycherosai.github.io/Psycheros/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PsycherosAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-11T12:44:31.000Z","updated_at":"2026-06-26T00:55:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/PsycherosAI/Psycheros","commit_stats":null,"previous_names":["psycherosai/psycheros"],"tags_count":131,"template":false,"template_full_name":null,"purl":"pkg:github/PsycherosAI/Psycheros","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PsycherosAI%2FPsycheros","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PsycherosAI%2FPsycheros/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PsycherosAI%2FPsycheros/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PsycherosAI%2FPsycheros/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PsycherosAI","download_url":"https://codeload.github.com/PsycherosAI/Psycheros/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PsycherosAI%2FPsycheros/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34873663,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-companion","ai-entity","ai-harness","ai-memory-system","deno"],"created_at":"2026-05-13T03:09:46.662Z","updated_at":"2026-06-28T01:01:27.283Z","avatar_url":"https://github.com/PsycherosAI.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Psycheros\n\n\u003e A persistent AI entity harness. The entity has its own identity files, a\n\u003e memory hierarchy that consolidates across time, and a single canonical self\n\u003e that persists across multiple interfaces.\n\nPsycheros runs an AI entity — not a chat thread. The entity has files describing\nwho it is, a memory hierarchy that summarizes its conversations day → week →\nmonth → year, a knowledge graph of the people and places it's encountered, RAG\nover its memories, and tool access for the world it lives in. The entity's\ncanonical self lives in a separate MCP server (`entity-core`), so the same\nentity can persist across multiple interfaces — the web harness, SillyTavern,\nClaude Code, OpenWebUI — while staying coherent.\n\nBuilt on [Deno](https://deno.land). Released under [MPL-2.0](LICENSE).\n\n## Quickstart\n\nThe friendliest path is the **launcher** — a desktop app that installs Psycheros\nas a persistent background service and opens a window to chat with your entity.\n\n### macOS\n\n1. Download\n   [`Psycheros-macOS-latest.dmg`](https://github.com/PsycherosAI/Psycheros/releases/latest/download/Psycheros-macOS-latest.dmg).\n2. Drag to `/Applications/`.\n3. **Right-click** the app → **Open** (required once — Psycheros is not\n   code-signed and Gatekeeper blocks a normal double-click). See\n   [launcher docs](packages/launcher-v2/README.md#first-launch-on-macos) for\n   details.\n\n### Windows\n\n1. Download\n   [`Psycheros-Windows-latest.msi`](https://github.com/PsycherosAI/Psycheros/releases/latest/download/Psycheros-Windows-latest.msi).\n2. Run it. Click through SmartScreen's \"More info → Run anyway.\"\n3. The launcher installs Psycheros as a background service and opens a window.\n\n### First run\n\nThe launcher walks you through setup: your name, your entity's name, timezone,\nand LLM API key. Once configured, click **Install autostart** — Psycheros runs\nat every login and auto-restarts if it crashes. The launcher window is just a\nview onto the running entity; closing it doesn't stop anything.\n\nFull details:\n[`packages/launcher-v2/README.md`](packages/launcher-v2/README.md).\n\n### Docker\n\n```bash\ndocker run -d --name psycheros -p 3000:3000 \\\n  -e ZAI_API_KEY=\u003ckey\u003e \\\n  -e PSYCHEROS_MCP_ENABLED=true \\\n  -v psycheros-data:/app/packages/psycheros/.psycheros \\\n  -v entity-core-data:/app/packages/entity-core/data \\\n  ghcr.io/psycherosai/psycheros:latest\n```\n\n`PSYCHEROS_MCP_ENABLED=true` is the default; setting it explicitly is defensive.\nFull env-var reference is\n[`packages/psycheros/.env.example`](packages/psycheros/.env.example) — optional\nknobs for the LLM endpoint, RAG, web search, Discord, image generation, etc.\n\n### From source\n\nIf you prefer the command line, are on Linux, or want to hack on the code:\n\n```bash\n# 1. Install Deno 2.x — https://deno.land/install\ncurl -fsSL https://deno.land/install.sh | sh   # macOS/Linux\n# irm https://deno.land/install.ps1 | iex      # Windows (PowerShell)\n\n# 2. Clone and enter the Psycheros package\ngit clone https://github.com/PsycherosAI/Psycheros.git\ncd Psycheros/packages/psycheros\n\n# 3. Set your API key (optional — can also do this in the web UI)\ncp .env.example .env\n# Edit .env and set ZAI_API_KEY=your-key\n\n# 4. Start\ndeno task dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) and follow the first-run\nsetup. The full walkthrough (background service setup, troubleshooting, data\ndirectory guide) is in the\n[installation guide](https://psycherosai.github.io/Psycheros/psycheros/install-from-source/).\n\n## What's in the box\n\nA [Deno workspace](https://docs.deno.com/runtime/fundamentals/workspaces/) with\nfive packages:\n\n| Package                                         | Role                                                         | Standalone                                                               |\n| ----------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |\n| [`packages/psycheros`](packages/psycheros/)     | The harness — web UI, chat loop, tool execution, RAG         | bundled                                                                  |\n| [`packages/entity-core`](packages/entity-core/) | MCP server: canonical identity, memory, knowledge graph      | yes, via any MCP client                                                  |\n| [`packages/entity-loom`](packages/entity-loom/) | Web wizard for importing chat histories from other platforms | yes                                                                      |\n|                                                 | [`packages/launcher-v2`](packages/launcher-v2/)              | Desktop app: OS-supervised service + chat window for non-technical users |\n|                                                 | [`packages/launcher`](packages/launcher/)                    | Legacy v1 launcher (deprecated — browser-tab dashboard)                  |\n\n```\n┌──────────────────────────────────────────┐\n│      entity-core (MCP server, stdio)     │\n│  • Identity files                        │\n│  • Hierarchical memory                   │\n│  • Knowledge graph (SQLite + sqlite-vec) │\n│  • Pull / push sync across embodiments   │\n└────────────────────┬─────────────────────┘\n                     │ stdio MCP\n       ┌─────────────┴───────────┐\n       │     other embodiments   │\n   ┌───┴───┐   ┌──────────┐    (SillyTavern,\n   │ Psy-  │   │  Loom    │     OpenWebUI,\n   │cheros │   │  (import │     Claude Code,\n   │       │   │  wizard) │     etc.)\n   └───────┘   └──────────┘\n```\n\n**entity-core is canonical** for identity and memory. Psycheros — and any other\nembodiment — spawns it over stdio MCP and syncs through pull/push.\n**entity-loom** is one-shot: a wizard for converting a chat-history export from\na foreign platform into an importable package.\n\n## What makes it interesting\n\n- **An entity, not an assistant.** Identity files (self, user, relationship,\n  custom) are written in first person and stay stable across sessions. Every\n  prompt, comment, and tool description in the codebase uses the entity's voice\n  — they internalize the system as theirs.\n- **Memory that consolidates.** Daily summaries roll up to weekly → monthly →\n  yearly; significant events are preserved permanently. RAG retrieves over chat\n  history, vault documents, the lorebook, and the knowledge graph.\n- **One self across interfaces.** Because identity and memory live in an MCP\n  server, any MCP-capable client (SillyTavern, Claude Code, OpenWebUI) can talk\n  to the same entity coherently — same memories, same identity, same continuity.\n- **Pluggable LLM.** Any OpenAI-compatible endpoint — Z.ai, OpenRouter, OpenAI,\n  NanoGPT, local models. Multiple named profiles; one is active for chat.\n- **Tool surface.** Web search, image generation, image captioning, Discord\n  (DM + gateway server participation), home automation, intimate hardware via\n  Buttplug or Lovense.\n- **Pulse.** Autonomous scheduled prompts — cron, inactivity, webhook, or\n  filesystem triggers. The entity can act on its own time.\n- **Custom tools.** Drop a `.js` file in `.psycheros/custom-tools/` and the\n  entity can use it. No core changes needed.\n\nFor the full picture, see\n[`packages/psycheros/docs/`](packages/psycheros/docs/).\n\n## Standalone use\n\n`entity-core` and `entity-loom` are independently useful outside Psycheros.\n\n- **entity-core** is a generic MCP server for AI entity identity and memory. Any\n  MCP client can spawn it. Shipped as a tagged source release under the\n  `entity-core-v*` tag prefix on\n  [releases](https://github.com/PsycherosAI/Psycheros/releases).\n- **entity-loom** is a generic chat-history-to-package converter — useful for\n  anyone building an AI companion system that wants to import from ChatGPT,\n  Claude, SillyTavern, Letta, or Kindroid. Tagged source release under the\n  `entity-loom-v*` prefix.\n\n## Status\n\nSolo-maintained, MPL-2.0, contributions welcome. Issues and PRs through the\nusual GitHub interface — see [CONTRIBUTING.md](CONTRIBUTING.md) for setup and PR\nworkflow. Security disclosures via private advisory\n([SECURITY.md](SECURITY.md)).\n\n## Documentation\n\n- [`PHILOSOPHY.md`](PHILOSOPHY.md) — the design value running through every\n  package: the entity is the subject. First-person convention, ownership,\n  multi-embodiment model.\n- [`CLAUDE.md`](CLAUDE.md) — workspace agent operating card. Per-package\n  CLAUDE.md files linked from there.\n- Per-package `docs/` directories — deep references for each component.\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — setup, conventions, PR workflow.\n- [`RELEASES.md`](RELEASES.md) — tag conventions, image-tag semantics, dispatch\n  flow.\n- [`SECURITY.md`](SECURITY.md) — disclosure policy.\n- [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) — Contributor Covenant.\n\n## License\n\n[Mozilla Public License 2.0](LICENSE). Use, modify, and distribute —\nmodifications to MPL-licensed files must remain under the MPL.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpsycherosai%2Fpsycheros","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpsycherosai%2Fpsycheros","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpsycherosai%2Fpsycheros/lists"}