NeoPsyke

The idea

NeoPsyke is organized around three modules inspired by Freud's structural model, wired into a continuous loop where motivation, planning, and governance are separate, explicit, and always running.

• Id -- generates motivation.
• Ego -- mediates between motivation and reality.
• Superego -- enforces governance and self-control.

LLMs simulate the internal cognitive roles. Around that core, NeoPsyke provides short-term, long-term, and episodic memory, durable and recurring goals, and a layered security model built into the runtime.

Why it's different

How it works

1. Stimulus — A stimulus reaches the SensoryCortex: a user message, an Id impulse, a goal signal, tool feedback, or a timer cue. Each carries security metadata.
2. Planning — The Ego attends to the highest-priority input, forms an intention, and the DecisionVerifier checks whether it is grounded and ready to commit.
3. Governance — The Superego judges the candidate intention against policy and safety constraints before execution is allowed.
4. Execution — The MotorCortex executes the action through discovered plugins. Feedback re-enters the system as new stimuli, closing the loop.

The Ego runs in a bounded loop (configurable, default 180 steps per input) to prevent runaway reasoning. A meta-reasoner monitors decision pressure and intervenes if the planning chain stalls or loops.

For deeper runtime details, the security model, and why the project uses Kotlin, see the repository README and docs.

What exists today

This is not just a conceptual sketch. NeoPsyke already has a strong architectural base implemented in a full agent runtime with goals, memory, tools, integrations, and action control. It also has a powerful validation harness, including full record, replay, and divergence capabilities, that gives the project a solid development foundation. Even so, it remains a work in progress, with meaningful gaps in stability, evaluation, and breadth of action coverage.

• Internal motivation as a first-class module. The Id maintains bounded internal drives such as being useful, learning something, or seeking interaction. These accumulate pressure over time and can generate autonomous impulses when the system is idle.
• Explicit source separation. User messages, internal drives, tool feedback, goals, and timers all enter the system as typed stimuli with different origins and trust semantics. Internal impulses are not allowed to impersonate user requests.
• Structural governance. The Superego is not a moderation layer bolted on afterward. Governance is a first-class part of the loop, with deterministic policy checks and review before execution.
• An explicit action lifecycle. Instead of collapsing actions into a simple plan → execute pipeline, NeoPsyke moves them through observe → prepare → stage → authorize → commit → record. Higher-impact actions can be reviewed and approved through the dashboard before execution.
• Durable goals and memory. The runtime includes recurring and scheduled goals, short-term context, episodic recall, and long-term semantic memory.
• A practical agent runtime. The project already includes web search and browsing, a plugin-based action system, external integrations, and a local web dashboard for chat, observability, and action control.

Current limitations

The architecture is real and implemented, and the project already has a solid base, but it should still be evaluated as an experimental system rather than a mature general-purpose agent. The limitations should be stated plainly.

• The goal subsystem works in basic scenarios but remains unstable and needs much broader testing.
• The dashboard is intended for local, single-owner testing and debugging. It is not designed for multi-user or multi-tenant deployment.
• Prompt-injection defense is heuristic, not a full sandbox.
• Plugins run in-process as trusted code. Third-party isolation is not implemented yet.
• Memory retrieval and memory consolidation still need tuning, especially around over-filtering and LLM-dependent judgment.
• The evaluation suite is still limited in breadth. The Freud validation pipeline exists, but it still needs broader scenario coverage and stronger empirical validation.
• Prompt quality, planning quality, and governance quality still depend heavily on the quality of the underlying models.
• The current Id dynamics need much more experimentation and still leave substantial room for further exploration.
• The current set of actions and tools is still too limited for the agent to be broadly useful. Additional actions and tools will be added once the Ego loop and goal system are stable enough. Expanding the action surface too early would make the system harder to control safely.

Some omissions are deliberate. For example, NeoPsyke does not currently use sub-agents, not because delegation is uninteresting, but because trust propagation, authority boundaries, and containment need a deliberate security architecture behind them first.

Those are not footnotes. They are part of the current state of the project.

Quick start

Prerequisites: JDK 21+, at least one LLM API key, Docker optional. For contributors using the Freud validation harness, also install Go 1.26+.

See the Getting Started guide for the full first-run flow, sample prompts, the dashboard walkthrough, and setup notes that match the repository docs.

Read more

Get involved

NeoPsyke is experimental and under active development. Contributions, feedback, and ideas are welcome.

• Open an issue for bugs, questions, or feature proposals.
• Start with CONTRIBUTING.md for workflow and validation expectations.
• Read SECURITY.md for private vulnerability reporting.
• All PRs go through the Freud validation pipeline.
• Apache 2.0 licensed.