memoryblock is a lightweight framework for running isolated AI workspaces as local background workers. Instead of spinning up monolithic chatbots, you provision dedicated workspaces called blocks — each with its own monitor, memory, tools, and execution loop.

A devops block watches your servers. A research block scrapes and summarizes data. A home block coordinates everything. They run independently — no shared state, no crossed wires.

Terminology

Memoryblock uses specific terms that mean different things than the typical AI landscape. Understanding these will help you navigate the system:

| Term | What it is | Has its own | |:---|:---|:---| | Founder | You — the human user. Your profile lives in founder.md and is shared across all blocks so every monitor knows who it's working for. | Profile, preferences | | Block | An isolated workspace. Think of it as a container for an AI personality — its own directory with config, memory, logs, and tools. | Memory, config, permissions, logs, cron jobs | | Monitor | The intelligence inside a block. This is what other platforms call an "AI agent." Each monitor has a name, emoji, personality, and its own conversation loop. | Identity, personality, tool access, conversation history | | Agent | A sub-process spawned by a monitor for a specific task. Agents are ephemeral — they run, report back, and get terminated. Only monitors can create them. | Isolated workspace, limited tools, inbox |

Founder (you)
└── Block: home
    └── Monitor: 🤖 Nova  ← the AI running inside this block
        ├── Agent: "research"  ← temporary sub-task worker
        └── Agent: "writer"   ← another temporary worker

Monitors are persistent — they remember everything across sessions. Agents are disposable — they exist only for the task that spawned them.

Why Memoryblock?

🏗️ Block Architecture

Each block is an isolated workspace — its own memory, config, tools, and logs. Like containers, but for AI. Copy a folder to move a monitor to another machine.

⚡ Lightweight & Fast

No Docker. No Python runtime. No heavy dependencies. Ships as a single npm package, boots instantly on Bun or Node.js. Runs on a $5 VPS as comfortably as a MacBook Pro.

🧠 Persistent Memory

Monitors remember context across sessions via smart memory summarization. No repeated prompts, no lost context. Sessions auto-resume on crash recovery.

📡 Multi-Channel Sync

Start a conversation on CLI, continue it on the web dashboard, pick it up on Telegram — the same monitor, the same context, seamlessly.

🛡️ Safe by Default

Blocks are sandboxed. Dangerous commands pause for human approval. Safe commands auto-execute. Elevate to Superblock only when needed.

🔌 Model Agnostic

Native adapters for OpenAI, Anthropic, Google Gemini, and AWS Bedrock. Connect the model that fits your task.

Get Started in 60 Seconds

npm install -g memoryblock   # or: bun install -g memoryblock
mblk init                    # guided setup — pick your LLM provider
mblk start home              # your first monitor is running

That's it. You have a running monitor with persistent memory, file access, and a web dashboard.

Bun users: When available, mblk automatically uses Bun for ~2x faster startup. Works perfectly on Node.js too.

Talk to Your Monitor

Blocks are decoupled from the interface. Use whatever channel fits your workflow:

mblk start home                     # interactive CLI chat
mblk start home -d                  # background daemon mode
mblk start home --channel telegram  # route to Telegram
mblk web                            # web dashboard at localhost:8420

Built-In Tools

Every block ships with 30+ built-in tools — no plugins required:

| Category | Tools | |:---|:---| | Files | read_file · write_file · replace_in_file · append_to_file · copy_file · move_file · delete_file · create_directory · list_directory · search_files · find_files · file_info | | Shell | execute_command · run_lint · run_build · run_test | | Agents | create_agent · query_agent · message_agent · list_agents · terminate_agent | | Scheduling | set_pulse · list_pulses · remove_pulse · schedule_cron_job · list_cron_jobs · remove_cron_job | | Identity | update_monitor_identity · update_founder_info · send_channel_message | | System | system_info · get_current_time · list_blocks · get_token_usage | | Config | auth_read · auth_write · list_auth_providers · update_block_config |

Extend with Plugins

mblk add web-search     # SERP querying via Brave Search
mblk add fetch-webpage  # Extract and chunk web page content
mblk add agents         # Sub-agent orchestration
mblk add aws            # AWS service tools

Plugins auto-install if missing — when you create a block and select capabilities, memoryblock installs what's needed.

Token Efficiency

Memoryblock is designed from the ground up to minimize token consumption:

| Optimization | How it works | |:---|:---| | Lazy tool loading | Tools are only sent to the LLM after the monitor discovers them — saves ~2,500 tokens per turn | | Tool result trimming | Large outputs (file contents, command results) are automatically truncated in conversation history | | Smart memory compaction | When context grows large, the monitor summarizes key info and resets — no redundant history | | Session state recovery | Conversations persist to disk so you never re-explain context after a restart | | Discovery → Use → Compact cycle | Full tool schemas sent once, then compacted to a reminder for all subsequent turns |

Monitor → Agent Orchestration

Monitors can spawn agents for parallel work:

Monitor: 🤖 Nova (home block)
├── create_agent("research", "Find pricing for competitor X")
├── create_agent("writer", "Draft the comparison doc")
├── query_agent("research")  → gets results
├── message_agent("writer", "Here's the data from research...")
└── terminate_agent("research")  → cleanup

Agents run in the block's agents/ directory with their own isolated context. The monitor can message them asynchronously without blocking its own conversation. Agents are ephemeral — they can't create other agents, and they have a limited tool set compared to the monitor.

Background & Scheduling

Run blocks as background daemons with built-in cron scheduling:

mblk start ops-monitor -d          # daemon mode
mblk service install                # auto-start on boot (launchd / systemd)

Your monitor can schedule its own tasks:

"Schedule a cron job: check server health every hour"
→ schedule_cron_job("health-check", "0 * * * *", "Run uptime check on production servers")

The Pulse engine runs autonomously in the background, executing instructions without consuming LLM tokens unless explicitly configured to alert the monitor.

Permissions & Security

Blocks are sandboxed by default. Elevate only when needed.

| | Block (default) | Superblock | |:---|:---:|:---:| | Read/write own files | ✅ | ✅ | | Identity & communication tools | ✅ | ✅ | | Shell commands | ❌ | ✅ | | Files outside block directory | ❌ | ✅ | | Cross-block visibility | ❌ | ✅ |

mblk superblock ops-monitor        # grant full access
mblk superblock ops-monitor --off  # revoke

Interactive tool approval: When a monitor tries to run a command, you see exactly what it wants to execute and approve or deny — in the CLI, web dashboard, or Telegram.

Commands

| Command | What it does | |:---|:---| | mblk init | Guided setup wizard | | mblk create <name> | Create a new block | | mblk start [block] | Start block(s) — interactive or -d for daemon | | mblk stop [block] | Stop a block (or all blocks) | | mblk status | See all blocks and their state | | mblk config [target] | Edit config: auth, <block>, or global | | mblk superblock <block> | Grant/revoke full system access | | mblk update | Update and restart all services | | mblk web | Open the web dashboard | | mblk add / remove <plugin> | Manage plugins | | mblk delete <block> | Archive (or --hard delete) a block | | mblk reset <block> | Clear memory and session | | mblk service install | Auto-start on boot | | mblk shutdown | Stop everything |

| Command | What it does | |:---|:---| | mblk server start | Start API & web UI server | | mblk server stop | Stop the server | | mblk server status | Show server PID and URL | | mblk server token | View or regenerate auth token | | mblk restart | Full restart of blocks + server | | mblk restore <name> | Restore an archived block | | mblk permissions <block> | View/edit block permissions | | mblk settings [plugin] | View/edit plugin settings |

How It Works

~/.memoryblock/ws/
├── config.json          # global settings
├── auth.json            # provider credentials
├── founder.md           # your profile (shared across blocks)
└── blocks/
    ├── home/
    │   ├── config.json  # block settings, adapter, permissions
    │   ├── monitor.md   # monitor identity and personality
    │   ├── memory.md    # persistent context across sessions
    │   ├── session.json # crash-recovery session state
    │   ├── pulse.json   # autonomic background pulse instructions
    │   ├── agents/      # ephemeral sub-agent workspaces
    │   │   ├── research/
    │   │   │   ├── config.json  # sandboxed config
    │   │   │   ├── memory.md    # agent memory
    │   │   │   ├── inbox.md     # async messages from monitor
    │   │   │   └── logs/
    │   │   └── writer/
    │   │       └── ...
    │   └── logs/        # full conversation history
    └── ops-monitor/
        └── ...

Each block is fully self-contained. Back up a monitor by copying its folder. Move it to another server by pasting it. No databases, no migrations.

Architecture

Modular TypeScript monorepo with strict dependency boundaries:

| Package | Role | |:---|:---| | memoryblock | CLI entry point and setup wizards | | @memoryblock/core | Engine — Monitor, Gatekeeper, Memory Manager | | @memoryblock/tools | 30+ built-in tools (files, shell, system, auth, pulse) | | @memoryblock/api | REST & WebSocket server | | @memoryblock/adapters | LLM providers (OpenAI, Anthropic, Gemini, Bedrock) | | @memoryblock/channels | CLI, Web, Telegram + MultiChannelManager | | @memoryblock/daemon | Background process lifecycle | | @memoryblock/web | Web dashboard UI | | @memoryblock/types | Shared TypeScript interfaces | | @memoryblock/locale | i18n and formatting |

How We Compare

What's Coming

We ship 2-3 features per release. Here's what's next:

• Add Adapters : Ollama adapter (local models), OpenRouter, DeepSeek, and Groq
• Add Tools : Vision/Image tools, Process management
• Add Plugins : Broswer plugin
• Add Channels : Discord, Slack, and WhatsApp
• MCP protocol support

Contributing & Support

We welcome PRs! See CONTRIBUTING.md.

If memoryblock is useful to you, consider sponsoring the project or giving it a ⭐.

The memoryblock Ecosystem

memoryblock is a highly modular system. Here are the official packages:

The Core

• memoryblock - CLI orchestrator and command routing.
• @memoryblock/core - Engine runtime, memory manager, gatekeeper.
• @memoryblock/types - Shared TypeScript definitions and schemas.
• @memoryblock/locale - Localization strings and utilities.

Integrations & Tooling

• @memoryblock/adapters - LLM provider adapters (OpenAI, Anthropic, Bedrock, etc).
• @memoryblock/channels - Communication channels (CLI, Telegram, Web).
• @memoryblock/tools - Tool registry and built-in definitions.
• @memoryblock/daemon - Background process spawner and manager.
• @memoryblock/api - HTTP/WebSocket API server.
• @memoryblock/web - Front-end dashboard static files.

Plugins

• @memoryblock/plugin-installer - Plugin installer and registry manager.
• @memoryblock/plugin-agents - Secondary AI agents orchestrator.
• @memoryblock/plugin-aws - AWS integrations.
• @memoryblock/plugin-fetch-webpage - Web content fetching and parsing.
• @memoryblock/plugin-web-search - Web search capabilities.

License

Distributed under the MIT License. See LICENSE for more information.