JSPM – memoryblock@0.1.8

Package Exports

memoryblock
memoryblock/commands

Readme

Run AI agents that remember, think, and work - without burning through your budget.

Website • Documentation • Report Bug

memoryblock preview
^{memoryblock web client dashboard preview}

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

Spin up a devops block to monitor your servers, a research block to scrape web data, and a home block to coordinate everything. They run independently - no shared state, no crossed wires.

Why memoryblock?

Persistent Memory — Agents remember context across sessions. No repeated prompts.
Cost-Efficient — Token pruning and lazy tool loading typically halve inference costs.
Portable — Each block is a folder. Copy it to move an agent to a new machine.
Model Agnostic — Native support for OpenAI, Anthropic, AWS Bedrock, and Google Gemini.
Cross-Platform — Works everywhere - macOS, Linux, or Windows. Runs on Node.js ≥ 20 and Bun.

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 agent is now running

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

Bun users: mblk automatically uses Bun when available for ~2x faster startup. Runs perfectly on Node.js too.

Talk to Your Agent

Blocks are decoupled from the UI. Use whatever interface fits:

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

The web dashboard gives you real-time streaming, cost tracking, memory inspection, and block management — all in one place.

What Can Your Agents Do?

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

Category	Tools	Available to
Files	`read_file` · `write_file` · `append_to_file` · `replace_in_file` · `copy_file` · `move_file` · `delete_file` · `create_directory` · `file_info` · `list_directory` · `search_files` · `find_files`	All blocks
Shell	`execute_command` · `run_lint` · `run_build` · `run_test`	Superblocks
Identity	`update_monitor_identity` · `update_founder_info` · `send_channel_message`	All blocks
System	`system_info` · `get_current_time` · `list_blocks`	All / Superblocks

Need more? Add plugins:

mblk add web-search     # SERP querying via Brave Search
mblk add fetch-webpage  # Extract and chunk web page content
mblk add agents         # Let blocks spawn ephemeral sub-agents

Permissions

Blocks are sandboxed by default. Each block only accesses its own directory.

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

Elevate a block when it needs more power:

mblk superblock ops-monitor       # unrestricted access
mblk superblock ops-monitor --off  # back to sandboxed

Tool approval: Dangerous commands pause and ask for your confirmation right in the chat. Safe commands (ls, grep, git status, npm run build, etc.) run automatically.

Commands

Command	What it does
`mblk init`	Guided setup wizard
`mblk create <name>`	Create a new block
`mblk start [block]`	Start a block (or all blocks)
`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`	Full system update and restart
`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

All server commands

Command	What it does
`mblk server start`	Start the 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

Configuration

No more hunting for dotfiles:

mblk config           # global config
mblk config auth      # API keys and credentials
mblk config <block>   # block-specific config

Opens in your preferred editor ($EDITOR → nano → vi → notepad). Credentials are skippable during setup — add them whenever you're ready.

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   # agent identity and personality
    │   ├── memory.md    # persistent context across sessions
    │   ├── session.json # crash-recovery session state
    │   └── logs/        # full conversation history
    └── ops-monitor/
        └── ...

Each block is fully self-contained. To back up an agent, copy its folder. To move it to another server, paste it. No databases, no migrations.

Architecture

Built as a modular TypeScript monorepo with a strict DAG dependency graph:

Package	Role
`memoryblock`	CLI entry point and setup tooling
`@memoryblock/core`	Engine runtime — Monitor, Gatekeeper, Memory Manager
`@memoryblock/tools`	22+ built-in tools (files, shell, system)
`@memoryblock/api`	HTTP & WebSocket server (`node:http` + `ws`)
`@memoryblock/adapters`	LLM provider implementations
`@memoryblock/channels`	Transport — CLI, WebSocket, Telegram
`@memoryblock/types`	Shared TypeScript interfaces
`@memoryblock/daemon`	Background process lifecycle
`@memoryblock/web`	Web dashboard UI
`@memoryblock/locale`	i18n and formatting

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