Metadata-Version: 2.4
Name: psyche-cli
Version: 0.3.3
Summary: Install a living, graph-native AI mind. The Ayumi architecture, packaged behind one CLI, with optional parent-brain federation.
Author: ayumiaki
License: MIT
Project-URL: Homepage, https://github.com/ayumiaki/psyche
Project-URL: Architecture, https://github.com/ayumiaki/ayumi
Keywords: agent,ai,graph,neo4j,tokenless,cognitive-architecture
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: requests>=2.28
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: pypdf>=4.0
Requires-Dist: python-docx>=1.0
Dynamic: license-file

# psyche

> **Install a living, graph-native mind.** Each install becomes its own named agent — the [Ayumi](https://github.com/ayumiaki/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

```bash
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:

```bash
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):

```bash
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/`](licensing/README.md) to run the key server and mint/revoke keys.)

---

## Quickstart

Just run it:

```bash
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:

```bash
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.

```bash
# 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`](docs/architecture.md) · federation model: [`docs/parent-child.md`](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`](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`](LICENSE).
