Skip to content

About

Reference sample for Meko + AWS Strands Agents: an agent that persists every step of its reasoning to a Meko datapack over MCP, then audits the trail from a separate process after the run ends. Apache 2.0.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

meko-agent-strands-sample

Persist what your agent is thinking and doing — into Meko, over its remote MCP server.

This is a small Strands Agents agent that triages a batch of developer-community messages and writes a short digest. The digest itself is ordinary — the point of the sample is the other half: every step the agent takes — what it read, what it decided, why, and what it produced — is persisted into Meko as an audit trail, using the same remote MCP endpoint you'd wire any agent to.

About the message batch: the sample ships with a small built-in list of example messages (MOCK_DISCORD_MESSAGES in agent.py) styled as a developer Discord, so the whole thing runs with zero external accounts — no Discord bot, no token. The messages are the input to the demo, not the point of it. Swapping in a real source (a Discord fetch via discord.py, an export, a webhook sink) is a one-function change and everything else — the agent, the Meko audit trail — stays identical. See Swap in a real message source.

One run gives you two things:

  • the digest (the agent's actual output), and
  • a durable, queryable audit trail in Meko of the agent's reasoning and actions.

A separate audit process — no shared in-memory state — reads that trail back out of Meko, proving the "what was the agent thinking?" record outlives the run that created it.

Two keys, two planes, cleanly separated:

Plane What it is Credential
Data (memory + knowledge + audit) Meko, over its MCP server at https://mcp.mekodata.ai/mcp Your Meko API key
Inference Whatever model you bring A model key you already own — Meko never sees it

The default inference path is Vertex AI via LiteLLM using Application Default Credentials — no API key to manage. Anthropic and Bedrock are one env var away.

Here's where each piece sits — the two planes only meet inside agent.py:

flowchart LR
    subgraph inference["INFERENCE PLANE — your model key (Meko never sees it)"]
        A["agent.py\n(Strands agent)"] -->|LiteLLM / SDK| M["Vertex AI · Anthropic · Bedrock"]
    end
    subgraph data["DATA PLANE — your Meko API key"]
        MCP["Meko MCP server\nmcp.mekodata.ai/mcp"] --> DP["Datapack\nconversations · memories · audit trail"]
        DP --> YB[("YugabyteDB")]
    end
    A -->|"conversation_create\nconversation_add_message\nmemory_add"| MCP
    AUD["audit\n(separate process)"] -->|memory_search| MCP
    CD["Claude Desktop\n(mcp.json)"] -.->|same datapack| MCP
Loading

What the agent does, step by step

  1. OBSERVE   read the built-in       ──▶  logged to Meko as the run's first step
               example message batch         (raw input, before any model call)
  2. DECIDE    model triages the batch ──▶  logged to Meko as the decision step
               (urgent items + an                (digest output + reasoning + plan)
               explicit ATTENTION line)
  3. REMEMBER  durable facts from the   ──▶  memory_add: "agent flagged an outage
               output                              report after a deploy", etc.

Then, later and separately:

  audit        new process, no state    ──▶  memory_search reads the trail back:
                                             "what did the agent do, and why?"

Step 1 reads the sample's built-in message list — see Swap in a real message source to point it at a live Discord channel (or any other source) instead. Everything downstream is unchanged.

How it maps onto Meko

  • Step-by-step trace → conversation_create + conversation_add_message, one call per step, each carrying the step's input, output, a reasoning paragraph, and a plan list. This is the ordered "what was the agent thinking?" record.
  • Durable facts → memory_add, for the conclusions worth recalling later across any agent or run. (Meko also extracts memories server-side from posted turns; the sample adds a couple of explicit facts because they live in the agent's output, which turn-extraction — which reads the user side — wouldn't otherwise capture.)
  • Reading it back → memory_search, scoped to the datapack + agent_id.

Notice the agent doesn't need Meko tools attached to it to do its job — the persistence is wrapped around the agent. That's deliberate: it shows Meko as an audit/observability layer you can put around an agent you already have, not something the agent must be rebuilt for.

Why this architecture

The data layer is reached over MCP so it stays framework-independent: the same datapack is reachable from this Strands agent today, from Claude Desktop via mcp.json right now, and from any other MCP client later, without re-plumbing where the memory and audit trail live. The persistence is a managed audit/memory layer rather than a hand-rolled stack of Redis, pgvector, and log files, which means the trail is queryable, durable, and shared across agents and runs by default instead of something you build and operate yourself. That separation is the whole point of the two-plane split above: the data plane is a service you point at, and the agent on the inference plane stays swappable around it.


Prerequisites

  1. Python 3.13+ and uv (curl -LsSf https://astral.sh/uv/install.sh | sh). uv manages the virtualenv and can fetch a suitable Python for you.
  2. A Meko datapack and its MCP endpoint (https://mcp.mekodata.ai/mcp). You need the datapack UUID and a Meko API key (sent as an Authorization: Bearer header).
  3. A model. By default the sample uses Vertex AI via LiteLLM, authenticated with Application Default Credentials — so you need a GCP project you can call Vertex in (your principal needs the roles/aiplatform.user role on it) and a one-time gcloud auth application-default login. (Prefer a key instead? Use --provider anthropic with ANTHROPIC_API_KEY, or --provider bedrock.)

There is no Discord prerequisite — the sample runs against its built-in example messages until you choose to wire a real source.

Get your Meko key and datapack

The sample needs MEKO_DATAPACK_ID and MEKO_API_KEY. To get them:

  1. Sign up at mekodata.ai — a default datapack and an API token are provisioned automatically on signup; no configuration needed.
  2. Copy your API token from the dashboard. This is the value for MEKO_API_KEY (sent as Authorization: Bearer).
  3. Want a separate datapack for this sample? Create one from the dashboard, the CLI (meko datapack create --agent_name <name>), or via the MCP datapack_create tool.
  4. Copy the datapack's UUID — this is the value for MEKO_DATAPACK_ID. In the dashboard (cloud.mekodata.ai), open Datapacks in the sidebar, select your datapack, and use the copy button next to the ID field under the datapack's name. (It's also the last segment of the page URL: cloud.mekodata.ai/datapacks/<uuid>.)

Setup

git clone git@github.com:YugabyteDB-Samples/meko-agent-strands-sample.git
cd meko-agent-strands-sample

uv sync        # creates .venv, installs deps (fetches Python 3.13+ if needed)

cp .env.example .env
# edit .env — at minimum:
#   MEKO_API_KEY=<your Meko key>
#   MEKO_DATAPACK_ID=<a datapack UUID you own>
#   VERTEX_PROJECT=<a GCP project you can use Vertex in>   # for the default provider

Everything below runs through uv run (no manual venv activation needed).

The sample loads .env with override=True, so .env is authoritative — a variable already exported in your shell (e.g. a stale MEKO_API_KEY) will not silently shadow the value you set here.

Inference: Vertex AI via ADC (default — no API key)

The default model is vertex_ai/gemini-2.5-flash-lite in us-central1 (verified available there; gemini-3.1-flash-lite 404s in some projects/regions until it's enabled — override VERTEX_MODEL_ID once it is). Google disabled Gemini API-key creation for many projects, so the clean path is Application Default Credentials — your GCP principal just needs roles/aiplatform.user on the project:

gcloud auth application-default login          # one time; writes ADC to ~/.config/gcloud
export VERTEX_PROJECT=your-gcp-project         # or set GOOGLE_CLOUD_PROJECT
# (optional) override the model/region defaults:
export VERTEX_MODEL_ID=vertex_ai/gemini-2.5-flash-lite
export VERTEX_LOCATION=us-central1             # us-east5 if you use a Claude-on-Vertex model

On a remote/headless machine with no browser, use the no-browser flow:

gcloud auth application-default login --no-browser
# follow the printed instructions on a machine that has a browser

LiteLLM exchanges your ADC for a short-lived token automatically — there's no key in code or .env. To use a plain API key instead, set MODEL_PROVIDER=anthropic and ANTHROPIC_API_KEY.


Run it

1. run — do the work and persist the audit trail

uv run agent.py run

You'll see the agent read the built-in example messages, open a Meko audit trace, log the observe and decide steps, write durable memories for what it flagged, and print the digest plus the conversation id of the trail.

You should see (ids and the model's exact digest wording will differ):

[1/3] Pulled 6 Discord messages from 4 channels.
[2/3] Opened Meko audit trace 7b3c… on datapack <your-datapack-uuid> (agent_id=discord-digest-agent).
[3/3] Persisted observation + decision steps to the trace.

=== Digest ===
…the model's ranked digest of the items needing a human…
ATTENTION: possible MCP server outage after deploy

Audit trail persisted to Meko (conversation 7b3c…). Run `uv run agent.py audit` - even in a new process - to read it back.

The run prints Pulled N messages from M channels — with the sample's built-in list, that's the example batch in agent.py, not a live Discord fetch. Wire a real source (below) and the same line reports your real messages.

2. audit — read the trail back (new process)

uv run agent.py audit
# or ask a specific question:
uv run agent.py audit "did the agent flag any incident, and what was it?"

This process shares nothing with the first. It calls memory_search and answers from what the earlier run persisted — the audit record survived the run.

You should see the query echoed, then the facts the previous run wrote read back out:

Audit query: What did the Discord digest agent do, what did it flag, and why?

…memory_search results from Meko, including the fact the run persisted, e.g.…
On 2026-07-23T…, the Discord digest agent triaged 6 messages and reported 'ATTENTION: possible MCP server outage after deploy'. Incident flagged: True.

(These results were written by a *previous* `run` process and read back here from Meko - the audit record outlived the run that produced it.)

3. digest-only — the contrast

uv run agent.py digest-only        # same as: uv run agent.py run --no-persist

Same digest, nothing written to Meko. Run audit afterward and you'll see no new trail — which is exactly the difference the Meko layer makes.

Known blocker: 403 at the Meko edge

If run returns a 403 before any Meko tool responds, that is Meko's edge tier gating direct API-key traffic from a laptop — not a bug in this code or in yours. Confirm that direct-key access is enabled for your account before you start debugging. (The Tier B integration test detects this same pre-auth 403 and skips rather than failing, for the same reason.)


Swap in a real message source

The sample reads from a built-in Python list so it runs with no external accounts. To make it read a real Discord channel (or any other source), replace one function — the rest of the pipeline (the Strands agent, the Meko audit trail, audit) does not change.

In agent.py, the source is the MOCK_DISCORD_MESSAGES list, consumed at the top of cmd_run. Swap it for a real fetch that returns the same shape — a list of {"author", "channel", "text"} dicts. For Discord specifically, that means:

  1. Create a Discord application + bot in the Developer Portal and copy its bot token.
  2. Enable the Message Content Intent for the bot (required to read message text).
  3. Invite the bot to your server with Read Messages / Read Message History on the channel you want to digest, and note that channel ID.
  4. Fetch recent messages — e.g. with discord.py, or a one-shot REST call to GET /channels/{channel_id}/messages with an Authorization: Bot <token> header — and map each to {"author", "channel", "text"}.
  5. Add DISCORD_BOT_TOKEN and DISCORD_CHANNEL_ID to your .env.

This sample intentionally does not ship that integration, so it stays runnable with zero setup; the built-in batch is the demo's fixed input, and the swap point above is where a real source plugs in.


Running the tests

Two tiers (details in tests/README.md):

# Tier A — unit tests. Fast, no credentials, no network. The default gate.
uv run pytest -m "not integration"

# Tier B — integration. The REAL Meko loop: a `run` persists an audit trail and a
# separate `audit` process reads it back, then it cleans up after itself. Opt-in;
# skips unless creds are present.
uv run pytest -m integration

Tier A mocks both SDK surfaces (the Strands agent/model and the Meko MCPClient) and asserts the Meko call order/arguments, incident detection, the no-persist path, and make_model() config. Tier B needs MEKO_API_KEY + a throwaway MEKO_TEST_DATAPACK_ID (and inference creds for the run step); it's how you prove the live loop.


Files

File Purpose
agent.py The sample: read the example batch → digest → persist each step to Meko; plus audit to read it back.
meko_client.py Two helpers: the Strands MCPClient for Meko (data plane) and make_model() (inference — Vertex/Anthropic/Bedrock).
pyproject.toml Project metadata + dependencies, managed by uv (strands-agents[litellm], python-dotenv, google-auth; pytest in the dev group).
tests/ Tier A unit tests (no creds) + a Tier B integration test (real Meko). See tests/README.md.
.env.example Template for every env var the sample reads.
mcp.json Drop-in MCP server config for MCP-aware clients (e.g. Claude Desktop) pointing at the same datapack.

The Meko tools this sample uses

Verified against the Cloud endpoint (https://mcp.mekodata.ai/mcp) on 2026-07-23; the full catalog is larger. Every tool takes a scope ("read" / "write" / "admin") as its first arg. If a tool call fails with an unexpected-argument error, the server schema may have changed since verification — check the endpoint's tools/list.

  • conversation_create(scope, agent_id, datapack_id, title, metadata) — open an audit trace for a run.
  • conversation_add_message(scope, agent_id, datapack_id, conversation_id, input, output, reasoning, plan, metadata) — record one agent step, with its reasoning and plan.
  • memory_add(scope, text, agent_id, conversation_id, datapack_id) — persist a durable fact from the agent's output.
  • memory_search(scope, query, agent_id, conversation_id, datapack_id) — read the trail back out.

License

Apache-2.0. See LICENSE.

About

Reference sample for Meko + AWS Strands Agents: an agent that persists every step of its reasoning to a Meko datapack over MCP, then audits the trail from a separate process after the run ends. Apache 2.0.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages