memoryhub

Centralized, governed memory for AI agents.

MemoryHub provides a persistent memory layer for AI agents running on OpenShift AI, with scope-based access control, multi-tenant isolation, and an immutable audit trail. It works with any agent framework — LlamaStack, LangChain, Claude Code, Cursor, and more.

Status: Alpha (v0.5.1). Core operations are stable; curation and relationship APIs may evolve.

Installation

pip install memoryhub

Requires Python 3.10+.

Quick start

import asyncio
from memoryhub import MemoryHubClient

async def main():
    # API key mode (simplest):
    client = MemoryHubClient(
        url="https://mcp-server.apps.example.com/mcp/",
        api_key="mh-dev-abc123",
    )

    async with client:
        # Search memories
        results = await client.search("deployment patterns", max_results=5)
        for memory in results.results:
            print(f"[{memory.scope}] {memory.content[:80]}")

        # Write a memory
        written = await client.write(
            "FastAPI is the preferred web framework",
            scope="project",
            weight=0.85,
        )
        print(f"Created: {written.memory.id}")

asyncio.run(main())

server_url is accepted as an alias for url for backward compatibility.

OAuth 2.1 mode

Recommended for production multi-agent deployments:

import asyncio
from memoryhub import MemoryHubClient

async def main():
    # OAuth 2.1 mode (recommended for production):
    client = MemoryHubClient(
        url="https://mcp-server.apps.example.com/mcp/",
        auth_url="https://auth-server.apps.example.com",
        client_id="my-agent",
        client_secret="my-secret",
    )

    async with client:
        # Search memories
        results = await client.search("deployment patterns", max_results=5)
        for memory in results.results:
            print(f"[{memory.scope}] {memory.content[:80]}")

        # Write a memory
        written = await client.write(
            "FastAPI is the preferred web framework",
            scope="project",
            weight=0.85,
        )
        print(f"Created: {written.memory.id}")

        # Read it back
        memory = await client.read(written.memory.id)
        print(memory.content)

        # Update it
        updated = await client.update(written.memory.id, weight=0.9)
        print(f"Version: {updated.version}")

        # Campaign-scoped search (requires project enrollment)
        campaign_results = await client.search(
            "shared patterns",
            project_id="my-project",
            domains=["React", "Spring Boot"],
        )

asyncio.run(main())

Environment variables

Instead of passing credentials directly, use MemoryHubClient.from_env():

API key mode

export MEMORYHUB_URL="https://mcp-server.apps.example.com/mcp/"
export MEMORYHUB_API_KEY="mh-dev-abc123"

MEMORYHUB_SERVER_URL is accepted as an alias for MEMORYHUB_URL.

OAuth 2.1 mode

export MEMORYHUB_URL="https://mcp-server.apps.example.com/mcp/"
export MEMORYHUB_AUTH_URL="https://auth-server.apps.example.com"
export MEMORYHUB_CLIENT_ID="my-agent"
export MEMORYHUB_CLIENT_SECRET="my-secret"

client = MemoryHubClient.from_env()

Project configuration

MemoryHubClient.from_env() (and construction without an explicit project_config argument) auto-discovers .memoryhub.yaml by walking up from the current working directory. If found, the file's retrieval_defaults are applied to outbound calls whenever the caller omits the corresponding argument, and memory_loading.live_subscription controls whether the client subscribes to push updates on connect.

In practice that means a caller can write a plain search and inherit the project's retrieval policy:

client = MemoryHubClient.from_env()
async with client:
    # .memoryhub.yaml sets retrieval_defaults.max_results: 20
    # so this call transparently uses max_results=20
    results = await client.search("deployment patterns")

To opt out of auto-discovery, pass auto_discover_config=False:

client = MemoryHubClient.from_env(auto_discover_config=False)

Or pass an explicit ProjectConfig to the constructor to use a fixed policy regardless of cwd. The recommended way to generate .memoryhub.yaml is the memoryhub-cli wizard (memoryhub config init); see the repo root README for the split between project config (.memoryhub.yaml, committed) and connection config (~/.config/memoryhub/config.json, per-developer).

Sync usage

For non-async contexts, use the _sync variants:

from memoryhub import MemoryHubClient

client = MemoryHubClient(
    url="https://mcp-server.apps.example.com/mcp/",
    api_key="mh-dev-abc123",
)

results = client.search_sync("deployment patterns")

API reference

Core operations

Lifecycle

Relationships and curation

Session focus

Push notifications

Utilities

Version history is accessed via read(memory_id, include_versions=True, history_offset=0, history_max_versions=10).

All methods accepting project_id use it for campaign enrollment verification. When a target memory has scope="campaign", the server resolves campaign membership through project_id. The domains parameter on search() boosts domain-matching results (non-matching results still appear); on write()/update() it tags the memory with crosscutting knowledge domains.

Authentication

The SDK supports two authentication modes:

API key — Calls register_session automatically on connect. Suitable for development and single-operator deployments.

OAuth 2.1 — Uses the client_credentials grant. Token management is fully automatic: the SDK fetches, caches, and refreshes JWT access tokens transparently. Recommended for production multi-agent deployments.

The two modes are mutually exclusive. If both are provided, the constructor raises ValueError.

Further documentation

The SDK is one surface of the memory-hub monorepo. For deeper context:

• Architecture overview — System design, deployment topology, data flow
• MCP server tool reference — The 14 tools the SDK wraps, with parameter reference
• Memory tree data model — How scopes, branches, and versioning work
• Governance and authorization — RBAC, scope-based access, audit trail
• Agent memory ergonomics design — Full .memoryhub.yaml schema, retrieval defaults, session focus, and loading patterns
• Package layout — How memoryhub (this SDK) relates to memoryhub-core (server-side library) and memoryhub-cli

Links

• GitHub repository
• CLI (memoryhub-cli) — companion CLI client
• Issue tracker
• License (Apache 2.0)