Memory Portals

Reference implementation for SEP-2072: Memory Portals - portable context storage for MCP using chDB.

Memory Portals is an MCP extension that enables persistent, portable context storage using chDB embedded databases. It provides a standardized way to store and retrieve conversation context, tool outputs, and user data in portable .db files.

Features

• Persistent Storage: Data survives server restarts in portable .db files
• SQL Interface: Query data using familiar SQL syntax
• Schema Auto-Inference: Tables are automatically created from data structure
• Import/Export: Support for JSON, CSV, and Parquet formats
• MCP Integration: Full MCP tools and resources support

Installation

# Using uv (recommended)
uv pip install -e .

# Or with pip
pip install -e .

Quick Start

As an MCP Server

Run the server directly:

memory-portals

Or configure in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "memory-portals": {
      "command": "memory-portals"
    }
  }
}

Using the Python API

from memory_portals import MemoryPortal, PortalRegistry

# Create a portal
portal = MemoryPortal(
    namespace="myapp",
    portal_id="conversations",
    db_path="~/.memory-portals/myapp/conversations.db",
)

# Write data
portal.write("messages", [
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hi there!"},
])

# Query data
result = portal.query("SELECT * FROM messages WHERE role = 'user'")
print(result.data)

# Clean up
portal.close()

MCP Tools

The server exposes the following tools:

Tool	Description
memory_write	Write data to a portal table
memory_query	Execute SQL queries
memory_delete	Delete data with conditions
memory_import	Import from JSON/CSV/Parquet files
memory_export	Export to JSON/CSV/Parquet files
memory_view	Get portal info, schema, and stats
memory_list_tables	List all tables in a portal
memory_drop_table	Drop a table
memory_list_portals	List all registered portals

MCP Resources

Access portals and tables as resources:

• mem://{namespace}/{portal_id} - Portal metadata and schema
• mem://{namespace}/{portal_id}/{table} - Table data (limited to 1000 rows)

URI Scheme

Memory Portals uses the mem:// URI scheme:

mem://{namespace}/{portal-id}[/{table}][?query]

Examples:

• mem://conversation/default - Root portal reference
• mem://conversation/default/messages - Specific table
• mem://conversation/default/messages?limit=10 - With query parameters

Project Structure

ext-memory-portals/
├── pyproject.toml
├── src/
│   └── memory_portals/
│       ├── __init__.py
│       ├── server.py              # FastMCP server entry point
│       ├── core/
│       │   ├── portal.py          # MemoryPortal class
│       │   ├── database.py        # ChDBAdapter wrapper
│       │   ├── metadata.py        # _mcp_metadata table management
│       │   └── registry.py        # Portal registry
│       ├── uri/
│       │   └── parser.py          # mem:// URI parsing
│       ├── io/
│       │   ├── json_handler.py
│       │   ├── csv_handler.py
│       │   └── parquet_handler.py
│       └── models/
│           └── schemas.py         # Pydantic models
├── tests/
└── examples/
    └── basic_usage.py

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run linting
uv run ruff check src/

# Run the example
uv run python examples/basic_usage.py

Testing with MCP Inspector

npx @modelcontextprotocol/inspector memory-portals

License

MIT