Mneuma

Mneuma is a local-first identity and memory substrate for LLM systems.

It is designed for one Person at a time:

• Person = the one human the Mneuma world is built around
• presence = a named, returnable identity in relation to that Person
• thread = a conversation branch within one presence

Mneuma is not a hosted SaaS or generic vector-memory wrapper. It is an ownable substrate for giving otherwise flat LLMs continuity, memory, mood, and evolving identity.

Status: early alpha

What it is

Mneuma is infrastructure for giving one human-centered memory world to otherwise stateless LLM systems.

Use it when you want:

• durable memory with line-level provenance
• named presences that can return over time
• thread branching inside one presence
• bounded mood / lens / reflection state that stays inspectable and local-first
• explicit scope isolation across presences and threads in one workspace

What it is not

• not a hosted SaaS
• not a generic vector database wrapper
• not an agent framework that hides state behind opaque orchestration
• not a claim that the system is sentient, autobiographical, or unconstrained

What it does today

• Markdown as canonical storage
• SQLite + FTS5 derived index
• provenance-first retain / recall / reflect / inspect / edit / forget
• bounded interaction cognition:
  • attunement
  • impressions
  • experiences
  • lessons
  • lens shifts
  • mood
  • loop artifacts
• first-class presence and thread registries
• JavaScript bridge for tool-calling integrations

Core concepts

• Person
  • the one human Mneuma evolves around
• presence
  • a named, returnable identity with its own private continuity
• persona
  • the expressive style/voice layer of a presence
• thread
  • a branch within one presence
• shared memory
  • memory shared across presences for one Person
• presence memory
  • private identity memory for one presence

Install

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .

Then use either:

mneuma --help

or:

python3 -m mneuma --help

Quick start

Create a workspace:

mkdir -p ./demo-workspace
mneuma --root ./demo-workspace init

Create a presence:

mneuma --root ./demo-workspace presence-create --name Sarah

Create a thread inside that presence:

mneuma --root ./demo-workspace thread-create --presence-id prs_xxx --title "Release planning"

Write memory into that presence:

mneuma --root ./demo-workspace retain \
  --raw "Sarah prefers dry humor and terse replies." \
  --kind-hint opinion \
  --presence-id prs_xxx

Recall with provenance:

mneuma --root ./demo-workspace recall --query "dry humor" --presence-id prs_xxx -k 5

Run interaction attunement for that presence:

mneuma --root ./demo-workspace --interaction-layer-enabled attune \
  --presence-id prs_xxx \
  --message "maybe this is wrong, i'm not sure" \
  --turn-count 4 \
  --session-minutes 8

Verification story

Fast local verification:

python3 -m unittest discover -s tests -v

Live model-backed verification:

cp .env.example .env.local
# set OPENAI_API_KEY in .env.local or export it in your shell
OPENAI_API_KEY=... python3 scripts/live_openai_validation.py

The live validator creates a temporary workspace, creates a presence and thread, retains memory, recalls it with provenance, runs attunement, and completes a real OpenAI tool-calling loop against the local CLI.

Security and dependency checks:

python3 -m pip install bandit pip-audit
bandit -q -r src scripts
pip-audit

Main commands

Identity and continuity:

• init
• presence-create
• presence-list
• presence-inspect
• thread-create
• thread-list
• thread-inspect

Memory:

• retain
• recall
• reflect
• inspect
• edit
• forget

Interaction layer:

• attune
• ruminate
• reframe
• experience
• simulate
• lens
• mood
• loop

Interaction-layer commands require --interaction-layer-enabled. That flag gates:

• attune
• ruminate
• reframe
• experience
• simulate
• lens
• mood
• loop

JavaScript bridge

A small bridge is included at:

• examples/openai-memory-tools.mjs

It exports:

• MEMORY_TOOLS
• runMemoryTool(toolName, args)

It supports:

1. installed/global mneuma CLI
2. fallback to python3 -m mneuma from this repo with PYTHONPATH=src

This is the intended integration path for companion apps such as mneuma-chat. The exposed tool names are stable, and the bridge now ships explicit per-tool JSON schemas instead of catch-all permissive objects.

Secure local usage

• inspect --inner-state is intentionally high-sensitivity and private by default; only call it from trusted local tooling.
• Presence-scoped commands now fail closed on unknown presences instead of broadening to a wider person scope.
• inspect, edit, and forget honor the optional --presence-id / --person-id scope and reject cross-scope record access.
• CLI --json payloads must be JSON objects and are size-bounded so companion apps fail deterministically on malformed input.
• Canonical storage is local Markdown plus a derived SQLite index; Mneuma does not expose a network service in this release.

Minimal CLI verification path

mkdir -p ./demo-workspace
mneuma --root ./demo-workspace init
mneuma --root ./demo-workspace presence-create --name Sarah
mneuma --root ./demo-workspace thread-create --presence-id prs_xxx --title "Release planning"
mneuma --root ./demo-workspace retain --presence-id prs_xxx --raw "Sarah prefers dry humor." --kind-hint opinion
mneuma --root ./demo-workspace recall --presence-id prs_xxx --query "dry humor" -k 5
mneuma --root ./demo-workspace --interaction-layer-enabled attune --presence-id prs_xxx --message "maybe this is wrong"

For a live model-backed tool-calling verification run, see:

• scripts/live_openai_validation.py

Project layout

src/mneuma/              Python package
examples/                JS bridge example
docs/spec/               technical docs
tests/                   integration-style tests

Workspace data is created by init and should live outside the package source tree.

Documentation

• DOCS.md — practical usage guide
• docs/spec/mneuma-spec.md — technical spec
• docs/spec/mneuma-interaction-layer.md — interaction-layer behavior
• docs/spec/mneuma-lens-dynamics.md — lens and adaptation notes
• mneuma-threat-model.md — repo-grounded local-first threat model
• security_best_practices_report.md — prioritized AppSec review notes
• docs/research/memory-landscape-2026.md — short comparison memo against current memory repos

License

MIT

Contributing

Contributions are welcome. Start with:

• CONTRIBUTING.md
• SECURITY.md
• SUPPORT.md
• open an issue before large architectural changes