JSPM – memoryblock@0.0.1

Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (memoryblock) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

The lightweight agent OS. Isolated AI workspaces that remember, think, and run — on your machine.

Website • Documentation • Report Bug

memoryblock preview
^{memoryblock web client dashboard preview}

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

Server & advanced commands

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

	Memoryblock	OpenClaw	Goose	Claude Code
Runtime	Node.js / Bun	Node / Python	Rust	Node.js
Docker required	No	No	No	No
Isolated workspaces	✅ Blocks	❌	❌	❌
Multi-channel sync	✅ CLI + Web + Telegram	Multi-channel (separate)	CLI + Desktop	CLI only
Background daemon	✅ + OS service	✅	❌	Cloud only
Cron scheduling	✅ Native	✅	❌	Cloud only
Sub-agent orchestration	✅ Full lifecycle	Sessions	Swarm	Subagents
Token optimization	✅ Lazy + compact	Standard	Standard	Compaction
MCP support	🔜 Planned	❌	✅ Native	✅
Browser control	🔜 Planned	✅	❌	✅

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.

memoryblock