MoJoAssistant

Your AI remembers you. Your data stays on your machine.

Every AI assistant today forgets you the moment the conversation ends. MoJoAssistant sits between you and your AI systems — keeping your memory, context, and workflow state on your own hardware, then exposing everything through a clean tool surface that any AI client can use.

Current release: v1.4.2-beta

Why MoJo?

Problem	Without MoJo	With MoJo
AI forgets everything	Start from zero every session	Persistent memory across sessions, searchable by any role
Same personality for everyone	Generic assistant tone	Named roles with distinct personas that grow over time
No idea what AI did with your data	Trust the cloud provider	Append-only audit log — see exactly what left your device
Manual task scheduling	Remember to ask AI every morning	Cron tasks run automatically; HITL pauses when it needs you
One AI, one conversation	Parallel sessions, no coordination	Roles dispatch sub-tasks to each other; shared institutional memory
Privacy is a promise, not a guarantee	Data leaves your machine by design	Policy pipeline blocks dangerous calls before they execute

MoJo is not a chatbot. It's the infrastructure layer that makes AI assistants genuinely personal — they remember who you are, how you work, what matters to you, and they grow more calibrated over time.

Community

Questions, ideas, or just want to see what others are building?

Scan the QR code or click the badge to join. The community bot (@MoJoAssistant) is available to answer setup and contribution questions directly in Discord.

What You Get

Layer	What it does
Memory	Persistent conversation + document memory with semantic search; role-scoped knowledge isolation
MCP Server	14 hub tools for any MCP client — Claude Desktop, Claude Code, custom agents
Scheduler	Cron + one-shot task runner with role-based agentic execution; HITL pause/resume
Roles	Named AI personas with dynamic system prompts, tool access, data boundaries, and two-tier knowledge growth
Policy	Inline safety checker — blocks credential access, reverse shells, exfiltration; per-task `danger_budget` override
Behavioral Security	Parallel observer with per-role baselines; three-tier containment (LOW/MED/HIGH); honeypot sandbox
PII Scanner	Pattern-based detection for credentials, financial data, health info, infrastructure details
Dashboard	Browser UI — event log, tasks, role chat, policy violations, privacy report
Dreaming	Nightly memory consolidation: raw sessions → ABCD semantic archives → searchable knowledge base
Agent Learning	Failure-to-lesson pipeline; memory context injection at task start; per-role silo memory
BRIDLE	Growth framework — roles learn your preferences through memory, dreaming, and HITL validation
External MCP	Plug in external MCP servers (tmux terminal, Playwright browser) via config
Google Workspace	Calendar, Drive, Gmail via `external_agent` hub
Notifications	ntfy push, SSE stream, persistent event log

Quick Start

1. Clone with submodules

git clone --recurse-submodules https://github.com/AvengerMoJo/MoJoAssistant.git
cd MoJoAssistant

2. Run the installer

Linux / macOS:

./scripts/install.sh

Windows:

scripts\install.bat

The installer creates a venv, installs dependencies, runs a preflight check for required system tools (tmux, node, cargo), and creates startup scripts.

3. Check what works

python3 scripts/doctor.py --setup

This runs live probes against your system and shows exactly what's working and what needs setup — stable features, experimental features, and external tools. Run with --fix for an interactive guided setup wizard.

4. Configure environment

cp .env.example .env
# Edit .env — set API keys, LLM endpoint, MEMORY_PATH if needed

5. Start the server

# MCP over stdio (Claude Desktop)
python unified_mcp_server.py --mode stdio

# HTTP + MCP (dashboard, REST, scheduler daemon)
python unified_mcp_server.py --mode http --port 8000

# Docker (CPU — recommended for new users)
docker compose up

Run as a persistent service (optional)

Linux (systemd user service):

./scripts/install_service.sh          # install + start
./scripts/install_service.sh --stop   # stop + remove
./scripts/install_service.sh --status # status + logs

macOS (launchd user agent):

./scripts/install_service_macos.sh          # install + start
./scripts/install_service_macos.sh --stop   # stop + remove
./scripts/install_service_macos.sh --status # status + logs

Both service scripts auto-update the Claude MCP config to HTTP mode.

See Installation Guide and Quick Start for full setup. For contributor workflow standards, see Development Rules (AI-First, Community-Ready). For community Discord assistant design, see Discord Community Assistant Spec.

The 14 MCP Tools

All functionality is exposed through hub tools. Each hub dispatches to sub-actions.

Tool	What it covers
`get_context`	Orientation, attention inbox, recent events, task session log
`search_memory`	Semantic search across conversations and documents
`add_conversation`	Store a conversation turn; `scope="framework"` writes to shared cross-role store
`reply_to_task`	Send a HITL reply to a waiting agentic task
`memory`	Conversation management, document ingestion, stats
`knowledge`	Code/doc repo indexing and file retrieval
`config`	Runtime configuration, LLM resources, roles, system health (`doctor`, `doctor_improve`)
`scheduler`	Task lifecycle — add, list, get, remove, daemon control
`dream`	Memory consolidation pipeline — process, list, upgrade, distill_inbox, chat_bridge
`role`	Role CRUD — create, update, list, get role definitions
`dialog`	Role Chat — direct conversation with any role; session persistence; cross-role referral
`agent`	Coding agent lifecycle (Claude Code, OpenCode)
`external_agent`	Google Workspace gateway (Calendar, Drive, Gmail)
`task_session_read`	Read the full message transcript for a completed task session
`task_report_read`	Read the structured result report for a completed task

Example usage in Claude Desktop

Use the scheduler tool to add a daily research task for researcher at 9am.
Use the config tool to check what LLM resources are available.
Use the dream tool to list recent memory archives.

Roles and Agentic Tasks

Roles are named AI personas stored in ~/.memory/roles/{role_id}.json. Each role has its own system prompt (generated dynamically from role fields), tool access list, resource tier preference, and optional data boundary policy.

{
  "name": "Researcher",
  "persona": "Research analyst focused on AI and distributed systems",
  "capabilities": ["web_search", "memory_search", "memory_write"],
  "local_only": false,
  "schedule_cron": "0 9 * * 1-5"
}

Add a task via MCP:

{
  "tool": "scheduler",
  "args": {
    "action": "add",
    "type": "assistant",
    "role_id": "researcher",
    "description": "Research the latest papers on KV cache compression"
  }
}

Roles can dispatch sub-tasks (dispatch_subtask) with automatic depth limiting to prevent delegation loops.

When an agent runs out of iterations without finishing, it surfaces a HITL question instead of silently failing — reply "yes" to grant more cycles, "no" to close it out.

Two-Tier Role Knowledge

Roles learn in two layers:

Role-private (scope="role", default) — knowledge stays inside that role's store
Framework-shared (scope="framework") — patterns written here are visible to every role at task start

The executor auto-detects workflow problems (empty response loops, repeated rejection patterns) and writes a framework entry with diagnosis and mitigation hints — roles learn from each other's failures without manual curation.

Policy and Safety

Every tool call in an agentic task passes through an inline policy pipeline before execution. No tool call is made if a checker blocks it.

"policy": {
  "checkers": ["static", "content", "data_boundary", "context"],
  "denied_tools": ["bash_exec"],
  "danger_budget": 3
}

local_only: true is a one-liner shorthand that locks a role to free-tier local resources and blocks all external MCP calls.

Tasks can set danger_budget in config to override the role default for a single run — useful for high-privilege provisioning without permanently raising the role's budget.

Content patterns cover:

Secrets and credentials (API keys, SSH keys, .aws/credentials, .netrc)
C2 / reverse shells (/dev/tcp/, nc -e /bin/sh, socat, mkfifo)
Data exfiltration (curl --data to external URLs, scp, rsync outbound)
Privilege escalation (chmod SUID, crontab -e, LD_PRELOAD)

The Security Sentinel (~/.memory/roles/security_sentinel.json) runs nightly at 03:00, audits the EventLog, and writes a digest to memory — fully local, no external calls.

Memory Path

All persistent state lives under MEMORY_PATH (default: ~/.memory). Set it in .env to redirect everything to a project-local directory:

MEMORY_PATH=/path/to/your/memory

Substructure:

$MEMORY_PATH/
  conversations_multi_model.json   — conversation store
  scheduler_tasks.json             — task queue
  task_sessions/                   — agentic session logs
  roles/                           — role definitions + chat history
  dreams/                          — dreaming archives
  config/                          — personal config overlays
  events.json                      — event log

Dashboard

Available at http://localhost:{port}/dashboard on any running instance.

Live event log (SSE auto-update)
Scheduler task list with status, iteration logs, and session transcript
Cron task history — recurring tasks show last-run time and next-run countdown even while pending
Role Chat — persistent conversation UI for any role (/dashboard/chat)
News Briefing — daily tech/AI news from Scott (/dashboard/news)
Policy violation log

Protected by the dashboard password set in .env.

LLM Resources

MoJoAssistant routes LLM calls through a resource pool:

Local — LM Studio or any OpenAI-compatible server
Free API — OpenRouter free-tier with multi-account rotation and dynamic model detection
API — OpenRouter paid, OpenAI, Anthropic, Google

Configure via the config MCP tool at runtime — no server restart needed:

Use the config tool to show available LLM resources.
Use the config tool to approve the new lmstudio resource.

agentic_capable is tested per-resource via a smoke test (tool call → write_file → disk verify). Results are cached for 7 days and expire automatically — a recovered model isn't blocked indefinitely.

config(action="doctor_improve") analyses running system health and proposes concrete config fixes for unreachable resources, stale capability flags, and missing role tools.

External MCP Servers

MoJoAssistant can spawn or connect to external MCP servers alongside its own tools. Configure them in config/mcp_servers.json (system defaults) or ~/.memory/config/mcp_servers.json (personal overrides):

{
  "servers": [
    {
      "id": "tmux",
      "name": "tmux MCP",
      "transport": "stdio",
      "command": "~/.cargo/bin/tmux-mcp-rs",
      "args": ["--shell-type", "bash", "--config", "config/tmux-mcp.toml"],
      "category": "terminal",
      "enabled": true
    }
  ]
}

Two transport modes: stdio (MoJo spawns the process) and http (connect to a running server). The preflight checker validates required binaries (tmux, node, cargo) before install.

Browser automation — pick your backend:

Backend	Style	Install
Webwright (default)	Code-as-action (agent writes scripts)	`pip install webwright`
Playwright MCP	Step-by-step browser control	`npx @playwright/mcp@latest`

Both are enabled by default. Webwright is preferred for agentic tasks. See docs/guides/BROWSER_MCP_SETUP.md.

Documentation

Releases

v1.4.0-beta — Pluggable module architecture + Plugin SDK
v1.3.7-beta — Install infrastructure + use case catalog
v1.3.6-beta — CI hardening
v1.3.5-beta — Beta checklist closed
v1.3.4-beta — BRIDLE framework + security hardening
v1.2.16-beta Release Notes
Roadmap
All Releases

Docker

# CPU (recommended — uses root-level docker-compose.yml)
docker compose up

# AMD ROCm GPU
docker compose -f docker/docker-compose.yml up mojoassistant-rocm

HuggingFace model cache is mounted from the host — no re-download on rebuild. Health check: GET /health.

Configure your LM Studio endpoint and memory path in .env before starting:

cp .env.example .env
# edit .env — set LM_STUDIO_URL, MEMORY_PATH, DASHBOARD_PASSWORD

CI / CD

GitHub Actions on every push:

Smoke test — starts the server, polls /health, asserts status=healthy
Docker build — CPU image build to catch Dockerfile regressions
Docker publish — pushes to ghcr.io on main and version tags

Development

Agent and coding policy:

Before merging:

run pytest tests/ — 821 tests collected
run MCP Smoke Checklist for live MCP validation

Status

Active beta (v1.4.2-beta). Core memory, MCP, scheduler, policy, role chat, dreaming pipeline, behavioral security, agent learning loop, BRIDLE growth framework, and PII scanning are production-ready for personal use.

Stable vs Experimental

Stable (production-ready):

Memory system (4-tier, semantic search, role-scoped isolation)
Scheduler (cron + one-shot, HITL pause/resume, zombie detection)
MCP tool surface (14 hub tools)
Policy pipeline (static, content, data_boundary, context, sensitive_domain)
Role system (NineChapter dimensions, dynamic prompts, two-tier growth)
Dashboard (event log, tasks, role chat, news briefing)
Dreaming pipeline (A→B→C→D, inbox distillation)
Notifications (ntfy push, SSE stream)
BRIDLE growth framework (snapshots, dimension drift, HITL validation)
Pluggable module architecture (8 provider families, conformance suites)
Plugin SDK (scaffold, validate, sample plugins)
Docker install path (Dockerfile + docker-compose.yml in repo root)

Experimental (may change):

LLM resource selection (local models, LMStudio integration)
Agent execution on local models (Qwen, Gemma — tool-calling reliability varies)
OpenAI-compatible proxy (/v1/models, /v1/chat/completions)
Coding agent integration (OpenCode, Claude Code, CubeSandbox-backed sessions)
External MCP servers (tmux terminal, Playwright/Webwright browser)
Google Workspace integration (Calendar, Drive, Gmail)
Discord community bot
agency-agents persona import (184 personas)

Requires additional setup:

tmux terminal tools (requires tmux + cargo install tmux-mcp-rs) — see docs/guides/TMUX_MCP_SETUP.md
Browser tools — Webwright (pip install webwright) or Playwright (npx @playwright/mcp@latest) — see docs/guides/BROWSER_MCP_SETUP.md
Discord community bot (requires DISCORD_BOT_TOKEN) — see docs/integrations/DISCORD_COMMUNITY_ASSISTANT_SPEC.md
Google Workspace (requires gcloud + gws CLI) — see docs/guides/GOOGLE_WORKSPACE_SETUP.md
ntfy push notifications (requires ntfy.sh or self-hosted instance) — see docs/guides/NOTIFICATIONS_SETUP.md

Join the Community

Have questions or want to contribute? Join us on Discord — scan the QR code or use the invite link https://discord.com/invite/fTgpagh93.

Name		Name	Last commit message	Last commit date
Latest commit History 871 Commits
.github/workflows		.github/workflows
app		app
changelogs		changelogs
config		config
docker		docker
docs		docs
examples/plugins		examples/plugins
results		results
scripts		scripts
submodules		submodules
tests		tests
tools		tools
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
Coding Agents Rules.md		Coding Agents Rules.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
app_factory.py		app_factory.py
docker-compose.yml		docker-compose.yml
funding.json		funding.json
pyproject.toml		pyproject.toml
requirements-runtime.txt		requirements-runtime.txt
requirements.txt		requirements.txt
sitecustomize.py		sitecustomize.py
unified_mcp_server.py		unified_mcp_server.py

Folders and files

Latest commit

History

Repository files navigation

MoJoAssistant

Why MoJo?

Community

What You Get

Quick Start

1. Clone with submodules

2. Run the installer

3. Check what works

4. Configure environment

5. Start the server

Run as a persistent service (optional)

The 14 MCP Tools

Example usage in Claude Desktop

Roles and Agentic Tasks

Two-Tier Role Knowledge

Policy and Safety

Memory Path

Dashboard

LLM Resources

External MCP Servers

Documentation

Getting Started

Configuration

Architecture

Releases

Docker

CI / CD

Development

Status

Stable vs Experimental

Join the Community

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 21

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages