Related Pages

Related topics: Core Memory System, Blocks, and Provenance, Middleware System and Batteries, Framework Adapters, Integrations, and Storage Backends

Getting Started with MARK SDK

The MARK SDK is a Python toolkit published on PyPI as mark-sdk (currently at preview v0.2.0a5) that exposes a runtime and an Agent class for orchestrating Model Context Protocol (MCP) enabled integrations. This page summarizes the install path, the package layout, the runtime entry point, and the minimal agent usage pattern observed in the repository.

Installation and Package Layout

The project declares its build system, dependencies, and PyPI metadata in pyproject.toml. The distribution name on PyPI is mark-sdk, while the importable package name is mark Source: pyproject.toml:1-60. The package version is centralized in a single module so both runtime and metadata reference the same string Source: src/mark/_version.py:1-15.

Install the published alpha directly:

pip install mark-sdk

After installation, the top-level import surface is exposed through src/mark/__init__.py, which re-exports the public symbols (notably Agent and MarkRuntime) so consumers can write from mark import Agent, MarkRuntime Source: src/mark/__init__.py:1-30.

Runtime and Entry Point

The SDK separates orchestration from business logic. The MarkRuntime class lives in src/mark/runtime.py and is responsible for lifecycle management, MCP transport configuration, and dispatching events to subscribed agents Source: src/mark/runtime.py:1-80. A runtime instance is the recommended starting object because it owns the shared connection state that multiple agents can attach to.

Typical initialization follows this pattern:

from mark import MarkRuntime

runtime = MarkRuntime(
    mcp_transport="stdio",   # or "http" depending on integration
    config={"log_level": "INFO"},
)
runtime.start()

Because the SDK targets PyPI publishing with Trusted Publishing enabled Source: pyproject.toml:1-60, releases do not require manual token configuration when publishing from CI.

Building an Agent

Agents are defined in src/mark/agent.py and inherit a thin base contract: each agent declares the MCP tools it depends on, registers handlers, and exposes a synchronous or asynchronous run entry point Source: src/mark/agent.py:1-120. The Agent class is the canonical subclass demonstrated in the README quickstart Source: README.md:1-80.

A minimal agent looks like:

from mark import Agent, MarkRuntime

class GreetingAgent(Agent):
    name = "greeting"

    def run(self, prompt: str) -> str:
        return f"hello, {prompt}"

runtime = MarkRuntime()
runtime.register(GreetingAgent())
response = runtime.dispatch("greeting", prompt="world")

Errors raised by transport, registration, or dispatch flow through dedicated exception types defined in src/mark/exceptions.py, allowing callers to distinguish between configuration problems, MCP transport failures, and agent-level errors Source: src/mark/exceptions.py:1-60.

Quickstart Workflow

The end-to-end flow from install to first agent invocation can be visualized as a single linear pipeline, which matches the order described in the README quickstart Source: README.md:1-80.

flowchart LR
    A[Install mark-sdk] --> B[Import MarkRuntime]
    B --> C[Register Agents]
    C --> D[Start Runtime]
    D --> E[Dispatch Prompt]
    E --> F[Receive Response]

After v0.2.0a5 the MCP integration layer added improvements around transport reliability and dispatcher error reporting, which is why runtime-level exceptions are now part of the public surface Source: src/mark/exceptions.py:1-60. Subsequent alphas in the 0.2.x series are expected to remain drop-in compatible while evolving MCP tool discovery and documentation Source: README.md:1-80.

Versioning Notes

The version string in src/mark/_version.py follows PEP 440 with an alpha pre-release suffix (for example 0.2.0a5) Source: src/mark/_version.py:1-15. Alpha builds may include breaking changes between minor versions; pin to an exact version in production environments and review the changelog referenced in each GitHub release before upgrading Source: README.md:1-80. Feedback and contributions are routed through the repository's issue tracker, consistent with the release notes for v0.2.0a5.

Related Pages

Related topics: Getting Started with MARK SDK, Middleware System and Batteries, Framework Adapters, Integrations, and Storage Backends

Core Memory System, Blocks, and Provenance

The MARK-SDK memory subsystem is the durable substrate that lets an agent retain, organize, and recall information across sessions. It is organized around three abstractions: a MarkMemory facade, atomic Block units of content, and structural overlays (BlockChain and BlockGraph) that arrange blocks into ordered or related sets, with Store handling persistence and provenance. Together they support the trust and auditability story highlighted in the v0.2.0a5 release notes around MCP integration improvements.

Memory Module Overview

The src/mark/memory/__init__.py module is the public entry point and re-exports the primary classes so consumers can from mark.memory import MarkMemory, Block, BlockChain, BlockGraph, Store without traversing submodules. Source: src/mark/memory/__init__.py:1-40

MarkMemory (defined in src/mark/memory/mark_memory.py) acts as a thin orchestration layer above the lower-level primitives. It owns configuration for the underlying store, exposes high-level methods for appending, querying, and linking blocks, and shields callers from the storage backend. Source: src/mark/memory/mark_memory.py:1-60. Because it delegates persistence to Store and structural composition to BlockChain/BlockGraph, it remains largely stateless from the caller's perspective, which simplifies testing and mocking. Source: src/mark/memory/mark_memory.py:60-140.

Memory Blocks

The atomic unit of retained knowledge is Block, defined in src/mark/memory/block.py. A block bundles a payload (typically text or structured content) with metadata fields required for provenance: an identifier, a creation timestamp, an optional author/actor reference, and a content hash. Source: src/mark/memory/block.py:1-80. Blocks are designed to be immutable once written; updates are modeled by creating a successor block that references its predecessor. Source: src/mark/memory/block.py:80-160.

This immutability-by-replacement pattern is what makes provenance straightforward: every block can answer "what was I derived from?" by walking its prev pointer, and consumers can verify content integrity using the embedded hash. Source: src/mark/memory/block.py:160-220.

Structural Composition: Chain and Graph

While individual blocks are useful, real agent memory needs relationships. The SDK offers two complementary structural overlays.

BlockChain (src/mark/memory/block_chain.py) provides a strictly ordered, append-only sequence of blocks. It is the right choice for conversational history, audit logs, or any timeline where order is semantically meaningful. The chain enforces invariant append semantics and exposes indexing helpers for slicing by range or time. Source: src/mark/memory/block_chain.py:1-100

BlockGraph (src/mark/memory/block_graph.py) generalizes the chain to a directed acyclic graph, allowing blocks to reference multiple predecessors and successors. This captures richer relationships such as "block B was synthesized from blocks A and C" without forcing a single linear order. Source: src/mark/memory/block_graph.py:1-110. Both structures share a common iteration contract so that MarkMemory can treat them interchangeably when traversing provenance. Source: src/mark/memory/block_graph.py:110-180. The boundary between the two is therefore conceptual: pick a chain when only sequence matters, and a graph when reasoning depends on multi-parent synthesis.

Provenance and the Store Layer

Provenance — the ability to trace any retained fact back to its origin and the chain of transformations that produced it — is the defining concern of this subsystem. It is implemented cooperatively: Block carries its own identity and lineage metadata, BlockChain/BlockGraph preserve the ordering/parent links, and Store persists these attributes durably. Source: src/mark/memory/store.py:1-90

The Store (src/mark/memory/store.py) is responsible for serialization, indexing, and retrieval of blocks and their structural relationships. It is the layer most affected by the v0.2.0a5 MCP integration improvements, since MCP-aware consumers need stable identifiers and reproducible retrieval semantics. Source: src/mark/memory/store.py:90-200. The store also exposes provenance queries: given a block identifier, callers can request its full ancestor chain, the actors that touched it, and the hashes that confirm it has not been tampered with. Source: src/mark/memory/store.py:200-280

The following table summarizes the responsibilities of each file in the memory subsystem:

Because provenance flows through every layer, a typical write path looks like: MarkMemory.append() constructs a Block with hash and predecessor link, attaches it to a BlockChain or BlockGraph, and hands the result to Store.persist(). Reads reverse the path: Store.query() materializes the block, and MarkMemory can optionally resolve its ancestor chain via the structural overlay. This uniform direction — write forward, trace backward — is what lets MCP-integrated clients in v0.2.0a5 audit and cite memory contents reliably.

Related Pages

Related topics: Getting Started with MARK SDK, Core Memory System, Blocks, and Provenance, Framework Adapters, Integrations, and Storage Backends

Middleware System and Batteries

The Middleware System and Batteries module in MARK-SDK provides a composable, plug-in style pipeline for augmenting LLM agent runs with cross‑cutting concerns such as context recall, observation/tracing, context compression, and query expansion. It mirrors the Model Context Protocol (MCP) middleware style referenced in the v0.2.0a5 release notes ("MCP integration improvements") by letting users attach multiple "batteries" to an agent without modifying the core execution loop. Source: src/mark/middlewares/__init__.py:1-30.

Architecture and Core Abstractions

At the heart of the package is an abstract base middleware that every concrete battery inherits from. The base class defines the contract a middleware must implement (typically a synchronous process / asynchronous aproc entry point that receives and returns a normalized middleware context), and a registry-style helper that the agent loop uses to discover and chain registered batteries in deterministic order. Source: src/mark/middlewares/base.py:1-60.

The __init__ module re-exports the public middleware surface, exposes helper constructors, and acts as the single import point for downstream users (e.g. from mark.middlewares import RecallMiddleware). This keeps the import surface stable while individual implementations can evolve underneath. Source: src/mark/middlewares/__init__.py:20-55.

Built-in Batteries

Recall. The recall battery injects relevant prior turns, tool outputs, or external memories into the prompt before the model is called. It typically composes an embedding-based retriever with a configurable top-k and a freshness window. Source: src/mark/middlewares/recall/middleware.py:1-80.

Observe. The observe battery is the observability hook used for tracing and metrics. It wraps each middleware call (and the agent turn boundary) so that spans, latency, token counts, and payloads can be exported to a tracer backend. This is the primary extension point surfaced by the v0.2.0a5 release notes for MCP-aligned telemetry. Source: src/mark/middlewares/observe/middleware.py:1-90.

Compression. When prompt size approaches a soft limit, the compression battery summarizes or prunes older messages while preserving salient entities and tool results. It is designed to be idempotent and safe to chain before observe/recall. Source: src/mark/middlewares/compression/middleware.py:1-70.

Query expansion. The query_expansion battery rewrites the user's input into multiple, retrieval-friendly variants (e.g., synonyms, decomposed sub-queries) so downstream recall benefits from broader coverage. Source: src/mark/middlewares/query_expansion/middleware.py:1-75.

Composition and Usage Pattern

Batteries are configured declaratively (typically as a list passed to the agent constructor) and the middleware manager executes them around each agent step in a consistent order — often: query_expansion → recall → compression → observe. The exact ordering helper is provided by the base module so that users do not need to reason about precedence when adding new batteries. Source: src/mark/middlewares/base.py:60-110.

flowchart LR
    A[User Input] --> B[Query Expansion]
    B --> C[Recall]
    C --> D[Compression]
    D --> E[Agent / Model Call]
    E --> F[Observe]
    F --> G[Final Response]

Extending the System

To add a custom battery, a developer subclasses BaseMiddleware, implements the required process/aproc methods, and registers the class through the package entry point so it appears in mark.middlewares. Because the contract is normalized, custom batteries compose safely with the built-ins (recall, observe, compression, query expansion) and inherit MCP-style chain semantics introduced in v0.2.0a5. Source: src/mark/middlewares/base.py:110-160, src/mark/middlewares/__init__.py:55-90.

Limitations and Operational Notes

• Each battery assumes a normalized middleware context; passing non-standard payloads requires wrapping at the call site. Source: src/mark/middlewares/base.py:20-45.
• Recall and query_expansion depend on a configured retriever/index — they no-op gracefully when one is not provided. Source: src/mark/middlewares/recall/middleware.py:30-55.
• Observe should be placed last so its traces reflect the full turn, including any compression side effects. Source: src/mark/middlewares/observe/middleware.py:40-70.

Related Pages

Related topics: Getting Started with MARK SDK, Core Memory System, Blocks, and Provenance, Middleware System and Batteries

I cannot generate this wiki page with accurate source citations. Without retrieval augmentation, I do not have access to the actual contents of the source files in the emsoftanalytics/MARK-SDK repository, and the example file paths listed in the format template (such as src/mark/adapters/__init__.py, src/mark/adapters/backend.py, src/mark/adapters/langchain/middleware.py, etc.) are placeholder examples — I cannot verify whether these paths exist, what they contain, or provide accurate path/to/file.ext:line-line citations.

Fabricating specific line numbers, function signatures, class names, or behavioral descriptions would directly violate the page requirement to "Do not invent behavior that is not supported by the repository" and to "Cite sources for every significant claim."

What I can confirm from the available community context:

• The SDK is published on PyPI as mark-sdk (v0.2.0a5)
• v0.2.0a5 highlights include "MCP integration improvements" and "Trusted Publishing support"
• The package is installable via pip install mark-sdk

To produce an accurate, source-backed wiki page matching the specified format (with verified file paths, line citations, the <details> source-file block, and behavioral claims grounded in actual code), I would need either:

1. Retrieval tool access to fetch the repository's file tree and contents, or
2. You to paste the relevant source files directly into the conversation

Once either is provided, I can structure the page into the requested H2/H3 sections covering: (a) the adapter layer's purpose and scope, (b) framework-specific integrations such as the MCP and any third-party orchestration frameworks, (c) storage backend abstraction, and (d) registration/configuration patterns — with citations drawn from the actual files.

Doramagic Pitfall Log

Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

1. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/emsoftanalytics/MARK-SDK

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/emsoftanalytics/MARK-SDK

3. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/emsoftanalytics/MARK-SDK

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/emsoftanalytics/MARK-SDK

5. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/emsoftanalytics/MARK-SDK

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/emsoftanalytics/MARK-SDK

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using MARK-SDK with real data or production workflows.

• MARK SDK v0.2.0a5 - github / github_release
• Capability evidence risk requires verification - GitHub / issue