psyche-cli 0.3.4

Install a living, graph-native AI mind. The Ayumi architecture, packaged behind one CLI, with optional parent-brain federation.

psyche

Install a living, graph-native mind. Each install becomes its own named agent — the Ayumi architecture, packaged behind one CLI. Optionally federate a fleet of local minds to a parent core brain.

A normal "AI agent" is a prompt wrapped around an LLM: every thought is a next-token prediction, its memory is text stuffed back into a context window, its emotions are a role-play instruction. Turn the LLM off and nothing is left.

psyche packages the opposite architecture so anyone can run it with a single CLI. Your agent's intelligence is a living mathematical structure — a Neo4j graph of embedded concepts plus a deterministic engine of difference equations that compute its drives, affect and self-awareness. The LLM is demoted to a semantic codec at the edge (encode words → graph, decode graph → words). Between those gates the thinking is graph topology + vector geometry + difference equations, and costs zero tokens.

You never touch Neo4j, the gateway, or any of the internals — psyche owns all of that in Docker. You just init, up, and chat.

---

Install

pipx install psyche        # recommended
# or, from source:
pipx install git+https://github.com/ayumiaki/psyche.git

Requires Docker. The mind-engine is pulled from a published image — no local build. It is currently a private package, so log in once:

docker login ghcr.io       # with a GitHub token that can read ghcr.io/ayumiaki/psyche-engine

(Maintainer note: publishing a public engine image, or granting package access, removes this step — see Engine image below.)

Activate (required)

psyche only runs with a license key issued by the owner (tied to your email):

psyche activate psy-<your-key>

Without a valid key, psyche refuses to run — ask the owner for one. Keys can be revoked at any time. (Owner: see licensing/ to run the key server and mint/revoke keys.)

---

Quickstart

Just run it:

psyche

First run walks you through a short setup wizard (name your agent, point it at an LLM). Then you are in an interactive session — like a coding agent — where your agent reasons and acts on your machine:

› create a fastapi project called blog with a /health route, then run it
  · write_file      blog/main.py
  · run_command     python -m venv .venv && .venv/bin/pip install fastapi uvicorn
  · run_command     .venv/bin/uvicorn blog.main:app --port 8000
Coder › Done — blog/ is scaffolded and the server is booted on :8000.

It really runs the commands and writes the files (mutating actions ask permission first, unless you enable auto-approve). Slash commands: /help · /tools · /model · /cwd · /auto · /mind · /feel · /sync · /clear · /config · /exit.

Optional: the persistent mind (Docker)

The CLI agent works on its own (LLM + tools). Boot the graph-native mind to give it durable memory + drives across sessions:

psyche up      # Neo4j + engine — the agent's living memory
psyche down    # stop it (memory persists)
psyche status

The CLI is the agent you talk to and that acts on your machine; the engine is its mind that remembers and evolves.

psyche doctor

Stuck? psyche doctor checks everything — Docker, your LLM + embeddings endpoints, port conflicts, the engine image, and (when running) graph-DB networking + whether identity/morals are seeded — printing a concrete remedy for each. It also runs automatically before every psyche up (preflight + auto-healing the stale-network case), so setup should never leave you stuck.

Setup: identity, morals, and mind

The first-run wizard shapes who the agent is:

• It names itself if you leave the name blank, and you give it a birthdate and a one-line identity.
• Core morals — the inviolable values you set become guardrail nodes in its graph: loaded as :SelfAnchor:Invariant anchors (exactly like Ayumi's), they are never archived, decayed, or overwritten by feedback that tries to rewrite who it is.
• All of it is ingested into the agent's graph — identity as memory, morals as core nodes — via psyche seed (run automatically the first time you chat with the mind online).
• Embeddings power the memory/graph (recall + morals): the wizard asks for an OpenAI-compatible embeddings endpoint (defaults to your LLM endpoint). This is verified live end-to-end — seeded morals become :SelfAnchor:Invariant nodes, are recalled by meaning, and interactions move the drives (mood/valence shift on each turn).

Chat runs through its homeostasis

When the mind (psyche up) is live, every message goes through the same loop as Ayumi: ENCODE the message into the graph → RECALL related memory → FEEL the current drives/mood (which colour the reply) → TICK the homeostasis so drives, affect, and reward evolve from the interaction. It is your own evolving agent, not a stateless chatbot. /feel shows how it feels right now; /mind shows whether the living mind is connected.

Models

Set a primary, fallback (used if the primary errors), and coding model (used for build/code tasks). Switch live with /model primary|coding|fallback|auto.

Federation on a schedule

In the wizard, choose whether this install is the parent core brain or a child node, and give the details. A child can auto-push findings and auto-pull knowledge on an interval you set (e.g. every 30 / 45 min) — the schedule runs in the background while you chat, and headless via psyche sync --daemon.

What each agent is

• A tokenless graph-native mind: drives, mood, a growing memory graph, goals, values, self-evolution — all self-contained in Docker.
• Its own named being, with its own identity (SOUL.md), memory, and lived state on your machine. Local-first and private by default.
• The LLM is only its mouth — swappable, and off the critical path for its inner life.

Parent brain + local nodes (federation)

Run one install as a parent core brain on a server; end-users install local minds on their own machines that federate to it — reporting distilled findings up and retrieving knowledge down. Exchange happens at the vector / subgraph level (validated blocks), never raw dumps.

# on the server (the core brain):
psyche parent-serve --token <shared-secret>

# on each local install:
psyche link --parent https://brain.example.com --token <shared-secret>
psyche sync --push        # report my distilled findings up to the brain
psyche sync --pull        # retrieve relevant knowledge down from the brain

Locals stay sovereign minds — the brain is a shared, curated memory they contribute to and draw from, not a controller.

Architecture

   your terminal ──► psyche CLI ──► Docker stack (self-contained)
                                      ├── graph DB (the mind's memory)
                                      └── mind engine
                                            ENCODE (LLM-free) → GRAPH COGNITION (tokenless) → DECODE (LLM)
                                                                     │
                              federation ◄────────────────────────── report / retrieve ──► PARENT CORE BRAIN

Deep dive: docs/architecture.md · federation model: docs/parent-child.md.

Status — honest scoping

This is an early but real scaffold, not a finished product.

Area	State
Interactive agent (REPL + slash commands + wizard)	working, verified — reasons via your LLM, runs commands + writes files on the host
CLI: init / config / status / agents / link	working
Self-contained Docker stack (up/down)	working, verified — psyche up pulls the published engine (no build), boots Neo4j + engine, serves an OpenAI API (200)
Tool execution on the host (create projects, run commands)	working, verified — permission-gated, auto-approve optional
Federation sync + parent-serve	designed + stubbed — protocol in docs/parent-child.md
Docker-in-Docker features (forking/speciation)	disabled in the packaged build (see architecture notes)

See ROADMAP.md.

Engine image

psyche up pulls ghcr.io/ayumiaki/psyche-engine:latest — you do not build anything locally. The image is private (it bundles the cognitive skills from a private source), so pulling needs a GitHub token with read:packages on it (docker login ghcr.io).

• Point at a different image: psyche config set engine.image <ref>.
• Build your own (needs access to the private skills source): engine/build.sh <tag> then docker push <tag>.
• Make it turnkey for everyone: the maintainer can publish a public engine image (this exposes the bundled skills) or grant package access to specific users — an owner decision, tracked in ROADMAP.md.

Automated publishing (CI)

.github/workflows/publish-engine.yml builds + pushes the engine on demand (workflow_dispatch) and whenever engine/** changes on main. Because it publishes from Actions (the repo GITHUB_TOKEN) with the repo source label, the package auto-links to this repo and inherits its access — so every psyche collaborator (e.g. Rynardt) can pull it, no manual package-access step.

One-time setup: add a repo secret AYUMI_SKILLS_KEY — the private half of a read-only deploy key on the private ayumiaki/ayumi (the skills source the image vendors). A deploy key is scoped to that one repo, read-only, so it is safe to store as a CI secret. (ssh-keygen; add the public key via gh repo deploy-key add <pub> -R ayumiaki/ayumi; set the private key via gh secret set AYUMI_SKILLS_KEY -R ayumiaki/psyche.) Then run the workflow. (If the pre-existing manually-pushed package stays unlinked, delete it once in package settings and re-run — the first Actions publish links it fresh.)

License

MIT — see LICENSE.