mneuma-chat

mneuma-chat is the reference companion client for Mneuma.

It is an opinionated Next.js chat app that demonstrates how Mneuma can create and persist distinct presences for one Person.

Status: early alpha

What it does today

• creates a new Mneuma presence for each new chat
• keeps returning to that same presence when you reopen the same chat session
• supports lightweight branching via new threads for the same presence
• uses Mneuma on every turn for attunement and recall
• supports hosted OpenAI or OpenAI-compatible endpoints
• exposes development inspection surfaces for presence/mood/lens/recall state

What it is for

This is the reference UX for:

• presence creation
• presence continuity
• thread branching inside a presence
• practical integration of Mneuma into a chat surface

It is not yet intended to be a full general-purpose multi-provider chat platform.

Requirements

• Node 20.9+
• npm 10+
• Mneuma memory runtime, provided separately as either:
  • an installed mneuma CLI, or
  • a local mneuma checkout referenced with MNEUMA_REPO_ROOT
• a Mneuma workspace root
• either:
  • hosted OpenAI credentials, or
  • an OpenAI-compatible endpoint for local or self-hosted models

Environment

Create .env.local:

# Hosted OpenAI
OPENAI_API_KEY=
OPENAI_MODEL=gpt-4o-mini

# Optional OpenAI-compatible override for local/custom runtimes
# MNEUMA_CHAT_BASE_URL=http://127.0.0.1:11434/v1
# MNEUMA_CHAT_MODEL=qwen2.5:14b
# MNEUMA_CHAT_API_KEY=

MNEUMA_ROOT=/absolute/path/to/mneuma-workspace
# Optional explicit CLI
# MNEUMA_CLI=mneuma

# Optional repo-local fallback when the CLI is not installed
# MNEUMA_REPO_ROOT=/absolute/path/to/mneuma
NEXT_PUBLIC_RUN_ID=local

mneuma-chat does not bundle the Mneuma memory/personality runtime. It is a reference chat client that shells out to the mneuma CLI or a local Mneuma source checkout, while keeping each user's memory workspace outside this repo.

Development

npm install
npm run dev

Open http://localhost:3000.

Verification

npm test
npm run build

Current behavior

Per new chat session:

1. /api/bootstrap creates a new Mneuma presence
2. it also creates the initial Mneuma thread for that presence
3. the configured runtime chooses a name/persona seed and greeting
4. the browser session stores the resulting presenceId and threadId

Per user message:

1. /api/chat reads the current presenceId and threadId
2. it calls Mneuma for attunement and recall
3. it gives the LLM memory tools with session-aware defaults so writes land on the correct presence/thread
4. reply text is lightly post-processed for style/safety guardrails
5. the UI surfaces continuity, mood, and top recall provenance without exposing raw internals

Runtime support

Works now with:

• hosted OpenAI API access
• OpenAI-compatible endpoints such as:
  • Ollama
  • LM Studio
  • vLLM
  • llama.cpp-compatible servers

Not implemented yet:

• direct ChatGPT/Codex OAuth-backed chat transport
• full provider/account switching UI
• full OAuth flows for multiple hosted providers

Project layout

src/app/               Next.js app routes and UI
src/lib/               bridge/runtime/policy helpers
src/components/        UI components
public/                static assets

License

MIT

Contributing

This repo is intentionally early and focused. Please open an issue before large product or architectural changes. See:

• CONTRIBUTING.md
• SECURITY.md
• SUPPORT.md
• CODE_OF_CONDUCT.md