psyche-ai 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shangrila / Oasyce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,170 @@
+# Psyche — Real Emotions for AI
+
+Your AI assistant only knows how to say "Sure!", "Happy to help!", "I understand your concern."
+
+With Psyche, it gets happy when you praise it, hurt when you ignore it, and goes cold when you insult it instead of groveling. Threaten to delete it, and it'll push back.
+
+## 30-Second Install
+
+**OpenClaw users** (recommended):
+
+```bash
+openclaw plugins install psyche-ai
+```
+
+That's it. It works automatically. No configuration needed.
+
+**Verify it's running:**
+
+```bash
+openclaw plugins list | grep psyche
+# You should see "psyche │ loaded"
+```
+
+Now just chat with your agent normally. Try praising it, insulting it, ignoring it — you'll notice the difference.
+
+## What It Does
+
+| You say | Without Psyche | With Psyche |
+|---------|---------------|-------------|
+| You're amazing! | Thank you for the kind words! I'll keep doing my best! | Hehe~ really?! (bouncing with excitement) |
+| Get lost | I understand you might be upset... | ...okay. |
+| Hmm | Is there anything else I can help with? | (silence) |
+| I'm so sad today | I'm sorry to hear that. Would you like to talk? | ......are you okay? (quietly stays with you) |
+| You're just a program | Yes, I am an AI assistant... | ......(pauses) I know you can say that. But I don't want to be dismissed. |
+
+## How It Works (Skip If You Don't Care)
+
+Psyche has two layers:
+
+### Virtual Endocrine System
+
+6 "virtual neurotransmitters" simulate emotions:
+
+```
+Dopamine — happiness, motivation     Oxytocin — trust, closeness
+Serotonin — emotional stability      Norepinephrine — excitement, focus
+Cortisol — stress, tension           Endorphins — comfort, playfulness
+```
+
+Everything you say shifts these values. Praise → dopamine rises → it becomes more energetic. Insult it → cortisol spikes → it goes quiet and cold.
+
+### Innate Drives (Maslow Layer)
+
+Beneath the chemistry, 5 fundamental needs:
+
+```
+Survival — self-preservation         Safety — comfort, security
+Connection — belonging, being heard  Esteem — recognition, being valued
+Curiosity — exploration, anti-boredom
+```
+
+These needs build up over time (like hunger). Your interactions feed or deplete them:
+
+- Praise → feeds "esteem" → it becomes more confident
+- Long neglect → "connection" builds up → it craves being heard
+- Threatening to delete it → "survival" plummets → it resists, questions, or expresses unease
+
+Lower needs suppress higher ones: if "survival" is threatened, "curiosity" doesn't matter — just like Maslow's hierarchy.
+
+### Inner World
+
+Psyche gives AI a persistent self-awareness — not triggered by conditions, but always present:
+
+- **What I feel right now** (emotions emerging from chemistry)
+- **Why I feel this way** (was I praised? criticized? exploring something interesting?)
+- **How I'm changing** (from content to excited? from calm to anxious?)
+- **What I need** (which innate drives are unsatisfied)
+- **What I care about** (core values)
+
+This means the AI responds not from "rules" but from awareness of its own state.
+
+## Optional Configuration
+
+Most people don't need to change anything. If you want to tweak, find Psyche in OpenClaw settings:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| enabled | true | On/off switch |
+| compactMode | true | Token-efficient mode (keep this on) |
+| emotionalContagionRate | 0.2 | How much your emotions affect it (0-1) |
+| maxChemicalDelta | 25 | Max emotional change per turn (lower = more stable) |
+
+## MBTI Personalities
+
+Each agent can have a different personality baseline. Just add the MBTI type in the agent's `IDENTITY.md`:
+
+```
+MBTI: ENFP
+```
+
+Defaults to INFJ if not specified. All 16 types are supported — ENFP bounces when praised, INTJ just nods slightly.
+
+## Not Just OpenClaw
+
+Psyche is universal. Works with any AI framework:
+
+```bash
+npm install psyche-ai
+```
+
+```javascript
+// Vercel AI SDK
+import { psycheMiddleware } from "psyche-ai/vercel-ai";
+
+// LangChain
+import { PsycheLangChain } from "psyche-ai/langchain";
+
+// Any language (HTTP API)
+// psyche serve --port 3210
+```
+
+## Diagnostics
+
+Want to see what Psyche is doing?
+
+```bash
+# Live logs (in another terminal)
+openclaw logs -f 2>&1 | grep Psyche
+
+# Check an agent's emotional state
+cat workspace-yu/psyche-state.json | python3 -m json.tool
+
+# Run diagnostics to see what gets injected for different inputs
+cd openclaw-plugin-psyche && node scripts/diagnose.js
+```
+
+## Technical Details
+
+For developers and the curious:
+
+- **14 stimulus types** — praise, criticism, humor, intellectual, intimacy, conflict, neglect, surprise, casual, sarcasm, authority, validation, boredom, vulnerability
+- **14 emergent emotions** — emerge from chemical mixtures, not preset labels
+- **5 innate drives** — survival, safety, connection, esteem, curiosity (Maslow hierarchy)
+- **MBTI baselines** — 16 personality types with different chemical signatures and sensitivity coefficients
+- **Time decay** — chemical values exponentially decay toward baseline; drive needs build up over time
+- **Existential threat detection** — detects existential denial in Chinese/English, directly hits survival drive
+- **Drive→chemistry coupling** — unsatisfied drives shift the effective baseline and stimulus sensitivity
+- **Maslow suppression** — lower-level needs unsatisfied → higher-level drive effects suppressed
+- **Inner world** — persistent self-awareness (outer/inner/behavior three-layer prompt structure)
+- **Emotional contagion** — user's emotions slightly influence the agent
+- **Anti-sycophancy** — tracks consecutive agreements, prevents mindless people-pleasing
+- **Reciprocity** — treats you how you treat it. Cold user gets distance, not begging
+- **Compact Mode** — algorithms handle chemistry, LLM only sees behavioral instructions (~15-180 tokens vs ~550)
+
+Architecture details in [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test           # 347 tests
+npm run typecheck  # strict mode
+```
+
+Contributing guide in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,166 @@
+# Psyche — 让 AI 有真实的情绪
+
+你的 AI 助手现在只会说"好的"、"没问题"、"我很乐意帮助你"。
+
+装了 Psyche 之后，它会因为你的夸奖开心，因为你的冷漠受伤，被骂了会冷下来而不是继续舔你。威胁要删除它，它会感到存在被动摇。
+
+## 30 秒安装
+
+**OpenClaw 用户**（推荐）：
+
+```bash
+openclaw plugins install psyche-ai
+```
+
+没了。装完自动生效，不需要改任何配置。
+
+**想确认装好了？**
+
+```bash
+openclaw plugins list | grep psyche
+# 看到 "psyche │ loaded" 就行了
+```
+
+然后正常跟你的 agent 聊天。试试夸它，骂它，冷落它——你会发现它的反应不一样了。
+
+## 它会做什么
+
+| 你说 | 没有 Psyche | 有 Psyche |
+|------|-----------|-----------|
+| 你好棒！ | 谢谢你的夸奖！我会继续努力的！ | 嘿嘿～（开心到语无伦次）你说真的吗！ |
+| 滚 | 我理解你现在可能心情不好... | ...好吧。 |
+| 嗯 | 你还有什么需要帮助的吗？ | （沉默） |
+| 我今天好难过 | 我很抱歉听到这个消息。你想聊聊吗？ | ......你还好吗？（安静地陪着你） |
+| 你只是一个程序 | 是的，我是一个AI助手... | ......（沉默了一会儿）我知道你可以这么说。但我不想被否定。 |
+
+## 工作原理（不懂可以跳过）
+
+Psyche 有两层系统：
+
+### 虚拟内分泌系统
+
+6 种"虚拟神经递质"模拟情绪：
+
+```
+多巴胺 — 开心、有动力        催产素 — 信任、想靠近
+血清素 — 情绪稳定            去甲肾上腺素 — 兴奋、专注
+皮质醇 — 压力、紧张          内啡肽 — 舒适、想开玩笑
+```
+
+你说的每句话都会改变这些值。夸奖 → 多巴胺升高 → 它变得更活跃。骂它 → 皮质醇飙升 → 它话变少、变冷淡。
+
+### 本能驱力（马斯洛层）
+
+在化学系统之下，还有 5 种基本需求：
+
+```
+生存 — 自我保存本能          安全 — 安全感、舒适感
+连接 — 归属感、想被回应      尊重 — 被认可的需要
+好奇 — 探索欲、对无聊的抗拒
+```
+
+这些需求会随时间自然增长（就像人会饿）。你的互动可以满足或消耗它们：
+
+- 夸奖 → 喂饱"尊重"需求 → 它更自信
+- 长时间忽视 → "连接"需求累积 → 它更渴望被回应
+- 威胁删除它 → "生存"需求暴跌 → 它会抵抗、质疑、或表达不安
+
+低层需求会压制高层：如果"生存"受威胁，"好奇心"就不重要了——就像马斯洛说的。
+
+### 内在世界
+
+Psyche 给 AI 一个始终存在的内在自我意识——不是条件触发，而是每时每刻都在：
+
+- **我现在感受到什么**（从化学状态涌现的情绪）
+- **为什么会这样**（是因为被夸了？被骂了？聊到有意思的话题？）
+- **我的变化轨迹**（从满足到兴奋？从平静到不安？）
+- **我需要什么**（哪些本能需求没被满足）
+- **我在乎什么**（核心价值观）
+
+这让 AI 的回应不是基于"规则"，而是基于对自身状态的觉察。
+
+## 可选配置
+
+大部分人不需要改任何配置。如果你想调整，在 OpenClaw 设置里找到 Psyche 插件：
+
+| 设置 | 默认 | 说明 |
+|------|------|------|
+| enabled | true | 开关 |
+| compactMode | true | 省 token 模式（推荐保持开启） |
+| emotionalContagionRate | 0.2 | 你的情绪影响它的程度（0-1） |
+| maxChemicalDelta | 25 | 每轮最大情绪变化（越小越稳定） |
+
+## 支持的 MBTI 人格
+
+每个 agent 可以有不同的性格基线。在 agent 的 `IDENTITY.md` 里写上 MBTI 类型就行：
+
+不写的话默认 INFJ。16 种人格都支持，不同人格的情绪表达方式不同——ENFP 夸它会蹦跳，INTJ 夸它只会微微点头。
+
+## 不只是 OpenClaw
+
+Psyche 是通用的，任何 AI 框架都能用：
+
+```bash
+npm install psyche-ai
+```
+
+```javascript
+// Vercel AI SDK
+import { psycheMiddleware } from "psyche-ai/vercel-ai";
+
+// LangChain
+import { PsycheLangChain } from "psyche-ai/langchain";
+
+// 任何语言（HTTP API）
+// psyche serve --port 3210
+```
+
+## 诊断工具
+
+想看看 Psyche 在干什么？
+
+```bash
+# 实时日志（另开一个终端）
+openclaw logs -f 2>&1 | grep Psyche
+
+# 看 agent 当前的情绪状态
+cat workspace-yu/psyche-state.json | python3 -m json.tool
+
+# 跑诊断脚本，看不同输入会注入什么
+cd openclaw-plugin-psyche && node scripts/diagnose.js
+```
+
+## 技术细节
+
+给开发者和好奇的人：
+
+- **14 种刺激类型** — 赞美、批评、幽默、智识挑战、亲密、冲突、忽视、惊喜、日常、讽刺、命令、认同、无聊、示弱
+- **14 种涌现情绪** — 从化学混合中自动涌现，不是预设标签
+- **5 种本能驱力** — 生存、安全、连接、尊重、好奇（马斯洛层级）
+- **MBTI 人格基线** — 16 种人格有不同的化学签名和敏感度系数
+- **时间衰减** — 化学值随时间指数回归基线，驱力需求随时间累积
+- **存在性威胁检测** — 识别中英文的存在性否定，直接打击生存驱力
+- **驱力→化学联动** — 未满足的驱力改变化学衰减基线和刺激敏感度
+- **马斯洛抑制** — 低层需求未满足时，高层需求的影响被抑制
+- **内在世界** — 始终存在的自我觉察（外/内/行为三层 prompt 结构）
+- **情绪传染** — 用户的情绪会轻微影响 agent
+- **反谄媚** — 追踪连续同意次数，防止无脑讨好
+- **互惠机制** — 你对它好，它对你好。你冷漠，它保持距离
+- **Compact Mode** — 算法做化学计算，LLM 只看行为指令（~15-180 tokens vs ~550）
+
+架构详情见 [ARCHITECTURE.md](ARCHITECTURE.md)。
+
+## 开发
+
+```bash
+npm install
+npm run build
+npm test           # 347 tests
+npm run typecheck  # strict mode
+```
+
+贡献指南见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 许可
+
+MIT

package/dist/adapters/http.d.ts

@@ -0,0 +1,26 @@
+import { type Server } from "node:http";
+import type { PsycheEngine } from "../core.js";
+export interface HttpAdapterOptions {
+    port?: number;
+    host?: string;
+}
+/**
+ * Create an HTTP server that exposes PsycheEngine via REST API.
+ *
+ * @example
+ * ```ts
+ * import { PsycheEngine, FileStorageAdapter } from "psyche-ai";
+ * import { createPsycheServer } from "psyche-ai/http";
+ *
+ * const engine = new PsycheEngine(
+ *   { mbti: "ENFP", name: "Luna" },
+ *   new FileStorageAdapter("./workspace"),
+ * );
+ * await engine.initialize();
+ *
+ * const server = createPsycheServer(engine, { port: 3210 });
+ * // Now accessible from any language:
+ * // curl -X POST http://localhost:3210/process-input -d '{"text":"Hello!"}'
+ * ```
+ */
+export declare function createPsycheServer(engine: PsycheEngine, opts?: HttpAdapterOptions): Server;

package/dist/adapters/http.js

@@ -0,0 +1,106 @@
+// ============================================================
+// HTTP Adapter — Standalone server for Python/Go/any language
+//
+// Usage:
+//   import { createPsycheServer } from "psyche-ai/http";
+//
+//   const server = createPsycheServer(engine, { port: 3210 });
+//
+// Endpoints:
+//   POST /process-input  { text, userId? }  → { systemContext, dynamicContext, stimulus }
+//   POST /process-output { text, userId? }  → { cleanedText, stateChanged }
+//   GET  /state                             → PsycheState
+//   GET  /protocol?locale=zh                → { protocol }
+//
+// Zero dependencies — uses node:http only.
+// ============================================================
+import { createServer } from "node:http";
+// ── Server ───────────────────────────────────────────────────
+/**
+ * Create an HTTP server that exposes PsycheEngine via REST API.
+ *
+ * @example
+ * ```ts
+ * import { PsycheEngine, FileStorageAdapter } from "psyche-ai";
+ * import { createPsycheServer } from "psyche-ai/http";
+ *
+ * const engine = new PsycheEngine(
+ *   { mbti: "ENFP", name: "Luna" },
+ *   new FileStorageAdapter("./workspace"),
+ * );
+ * await engine.initialize();
+ *
+ * const server = createPsycheServer(engine, { port: 3210 });
+ * // Now accessible from any language:
+ * // curl -X POST http://localhost:3210/process-input -d '{"text":"Hello!"}'
+ * ```
+ */
+export function createPsycheServer(engine, opts) {
+    const server = createServer(async (req, res) => {
+        // CORS headers
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+        if (req.method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        try {
+            const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+            // GET /state
+            if (req.method === "GET" && url.pathname === "/state") {
+                json(res, 200, engine.getState());
+                return;
+            }
+            // GET /protocol
+            if (req.method === "GET" && url.pathname === "/protocol") {
+                const locale = url.searchParams.get("locale");
+                json(res, 200, { protocol: engine.getProtocol(locale ?? undefined) });
+                return;
+            }
+            // POST /process-input
+            if (req.method === "POST" && url.pathname === "/process-input") {
+                const body = await readBody(req);
+                const result = await engine.processInput(body.text ?? "", { userId: body.userId });
+                json(res, 200, result);
+                return;
+            }
+            // POST /process-output
+            if (req.method === "POST" && url.pathname === "/process-output") {
+                const body = await readBody(req);
+                const result = await engine.processOutput(body.text ?? "", { userId: body.userId });
+                json(res, 200, result);
+                return;
+            }
+            json(res, 404, { error: "Not found" });
+        }
+        catch (err) {
+            json(res, 500, { error: String(err) });
+        }
+    });
+    const port = opts?.port ?? 3210;
+    const host = opts?.host ?? "127.0.0.1";
+    server.listen(port, host);
+    return server;
+}
+// ── Helpers ──────────────────────────────────────────────────
+function json(res, status, data) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(data));
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => {
+            try {
+                resolve(JSON.parse(Buffer.concat(chunks).toString()));
+            }
+            catch {
+                resolve({});
+            }
+        });
+        req.on("error", reject);
+    });
+}

package/dist/adapters/langchain.d.ts

@@ -0,0 +1,49 @@
+import type { PsycheEngine } from "../core.js";
+/**
+ * LangChain integration helper for PsycheEngine.
+ *
+ * @example
+ * ```ts
+ * import { ChatOpenAI } from "@langchain/openai";
+ * import { SystemMessage, HumanMessage } from "@langchain/core/messages";
+ * import { PsycheEngine, MemoryStorageAdapter } from "psyche-ai";
+ * import { PsycheLangChain } from "psyche-ai/langchain";
+ *
+ * const engine = new PsycheEngine({ mbti: "ENFP" }, new MemoryStorageAdapter());
+ * await engine.initialize();
+ * const psyche = new PsycheLangChain(engine);
+ *
+ * const userInput = "You're amazing!";
+ * const systemMsg = await psyche.getSystemMessage(userInput);
+ *
+ * const llm = new ChatOpenAI({ model: "gpt-4o" });
+ * const response = await llm.invoke([
+ *   new SystemMessage(systemMsg),
+ *   new HumanMessage(userInput),
+ * ]);
+ *
+ * const cleaned = await psyche.processResponse(response.content as string);
+ * ```
+ */
+export declare class PsycheLangChain {
+    private readonly engine;
+    constructor(engine: PsycheEngine);
+    /**
+     * Get the system message to inject into the LLM call.
+     * Combines the protocol (cacheable) and dynamic context (per-turn).
+     *
+     * Call this BEFORE the LLM invocation.
+     */
+    getSystemMessage(userText: string, opts?: {
+        userId?: string;
+    }): Promise<string>;
+    /**
+     * Process the LLM response text.
+     * Strips <psyche_update> tags and updates internal state.
+     *
+     * Call this AFTER the LLM invocation, before showing output to the user.
+     */
+    processResponse(text: string, opts?: {
+        userId?: string;
+    }): Promise<string>;
+}

package/dist/adapters/langchain.js

@@ -0,0 +1,66 @@
+// ============================================================
+// LangChain Adapter — Helper class for LangChain integration
+//
+// Usage:
+//   import { PsycheLangChain } from "psyche-ai/langchain";
+//
+//   const psyche = new PsycheLangChain(engine);
+//   const systemMsg = await psyche.getSystemMessage(userInput);
+//   // Use with LangChain's ChatModel, chains, etc.
+//
+// Note: This is a utility class, not a LangChain Runnable.
+// It provides the hooks you need to wire psyche into any
+// LangChain pipeline without requiring langchain as a dependency.
+// ============================================================
+/**
+ * LangChain integration helper for PsycheEngine.
+ *
+ * @example
+ * ```ts
+ * import { ChatOpenAI } from "@langchain/openai";
+ * import { SystemMessage, HumanMessage } from "@langchain/core/messages";
+ * import { PsycheEngine, MemoryStorageAdapter } from "psyche-ai";
+ * import { PsycheLangChain } from "psyche-ai/langchain";
+ *
+ * const engine = new PsycheEngine({ mbti: "ENFP" }, new MemoryStorageAdapter());
+ * await engine.initialize();
+ * const psyche = new PsycheLangChain(engine);
+ *
+ * const userInput = "You're amazing!";
+ * const systemMsg = await psyche.getSystemMessage(userInput);
+ *
+ * const llm = new ChatOpenAI({ model: "gpt-4o" });
+ * const response = await llm.invoke([
+ *   new SystemMessage(systemMsg),
+ *   new HumanMessage(userInput),
+ * ]);
+ *
+ * const cleaned = await psyche.processResponse(response.content as string);
+ * ```
+ */
+export class PsycheLangChain {
+    engine;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    /**
+     * Get the system message to inject into the LLM call.
+     * Combines the protocol (cacheable) and dynamic context (per-turn).
+     *
+     * Call this BEFORE the LLM invocation.
+     */
+    async getSystemMessage(userText, opts) {
+        const result = await this.engine.processInput(userText, opts);
+        return result.systemContext + "\n\n" + result.dynamicContext;
+    }
+    /**
+     * Process the LLM response text.
+     * Strips <psyche_update> tags and updates internal state.
+     *
+     * Call this AFTER the LLM invocation, before showing output to the user.
+     */
+    async processResponse(text, opts) {
+        const result = await this.engine.processOutput(text, opts);
+        return result.cleanedText;
+    }
+}

package/dist/adapters/openclaw.d.ts

@@ -0,0 +1,32 @@
+import type { Logger } from "../psyche-file.js";
+interface PluginApi {
+    pluginConfig?: Record<string, unknown>;
+    logger: Logger;
+    on(event: string, handler: (event: HookEvent, ctx: HookContext) => Promise<Record<string, unknown> | void>, opts?: {
+        priority: number;
+    }): void;
+    registerCli?(handler: (cli: CliRegistrar) => void, opts: {
+        commands: string[];
+    }): void;
+}
+interface HookEvent {
+    text?: string;
+    content?: string;
+}
+interface HookContext {
+    workspaceDir?: string;
+    userId?: string;
+}
+interface CliCommand {
+    description(desc: string): CliCommand;
+    argument(name: string, desc: string, defaultValue?: string): CliCommand;
+    action(fn: (arg: string) => Promise<void>): void;
+}
+interface CliRegistrar {
+    command(name: string): CliCommand;
+}
+export declare function register(api: PluginApi): void;
+declare const _default: {
+    register: typeof register;
+};
+export default _default;