# Meko

> Meko is an agent-native data layer that gives AI agents persistent memory, shared knowledge, and decision traces — unified on a distributed PostgreSQL backend (YugabyteDB). Multi-agent systems and multi-person teams collaborate through datapacks exposed over the Model Context Protocol (MCP).

## For agents reading this file

### Connect

1. User signs up at https://cloud.mekodata.ai and generates an API key under **Settings > API Keys**. Keys start with `mko_tkn_` and are shown once.
2. Register the shared MCP endpoint with that key:

```json
{
  "mcpServers": {
    "meko": {
      "url": "https://mcp.mekodata.ai/mcp",
      "headers": {
        "API_KEY": "<paste-your-api-key>"
      }
    }
  }
}
```

3. Preferred for Cursor, Claude Code, Claude Desktop, and Codex — portal one-liner (also installs agent skills / hooks where supported):

```sh
npx @yugabytedb/meko-mcp --client <client> --url "https://mcp.mekodata.ai/mcp" --api-key <paste-your-api-key>
```

Replace `<client>` with `cursor`, `claude-code`, `claude-desktop`, or `codex`. VS Code and other MCP clients use the manual JSON config above (see Connect via IDE).

OAuth (URL only, no API key) works for clients with a custom-connector flow; that path is on-demand unless skills are installed separately.

### Routing

- One MCP URL for every datapack: `https://mcp.mekodata.ai/mcp`. Pass `datapack_id` (or name) on tool calls to select a datapack; do not invent per-datapack URLs.
- Auth header name is `API_KEY` (not `Authorization` / Bearer). Key prefix is `mko_tkn_`.
- There is no released Python SDK. "Connect your AI app" / framework SDKs are under development. Integrate via MCP until those ship.
- Supported IDE / coding clients today: Cursor, Claude Code, Claude Desktop, Codex, VS Code.
- Tool catalog and calling conventions: [Meko MCP Server](/reference/mcp-server/). Do not send retired tool-level `scope` arguments.

### Suggested first tools

- List workspaces → `datapack_list`
- Remember a fact → `memory_add` (or ask the user to say "remember this")
- Search memory → `memory_search`
- Search uploaded docs → `knowledgebase_search`
- Save a chat turn → `conversation_create` then `conversation_add_message`

## Getting Started

- [Quick Start](/quick-start/): Use when onboarding — sign up, try WorkbenchLM, connect an AI client, then (later) a custom app
- [Explore Meko](/quick-start/explore-meko/): Use when adding first knowledge uploads and creating memories after connect

## Core Concepts

- [Datapacks](/architecture/core-concepts/datapacks/): Use when explaining isolation — one datapack bundles memory, knowledge, conversations, traces, and credentials
- [Memory](/architecture/core-concepts/memory/): Use when storing or recalling durable facts via vectors + graph (MAGE)
- [Learnings](/architecture/core-concepts/learnings/): Use when promoting private memory into collective memory or shared knowledge
- [Knowledge Bases](/architecture/core-concepts/knowledgebase/): Use when describing RAG over uploaded documents (`pg_dist_rag`)
- [Graph RAG](/architecture/core-concepts/graph-rag/): Use when answering entity-relationship / graph traversal questions over memory
- [Traces](/architecture/core-concepts/traces/): Use when explaining observability, conversation history, and chain-of-thought audit

## Architecture

- [How Meko Fits](/architecture/how-meko-fits/): Use when placing Meko in an agentic stack or comparing deployment models

## Guides

- [WorkbenchLM](/guides/workbench-lm/): Use when trying Meko in the portal chat with no local MCP install
- [Working with Memory](/guides/working-with-memory/): Use when adding, searching, listing, or promoting memories over MCP
- [Working with Knowledge Bases](/guides/working-with-knowledge-bases/): Use when building or querying document collections for RAG
- [Working with Artifacts](/guides/working-with-artifacts/): Use when storing or retrieving agent-generated files (`artifact_put` / `artifact_get`) across sessions or agents
- [Observability](/guides/observability/): Use when locating decision traces and conversation history in the portal

## Integrations

- [Connect via IDE](/integrations/connect-to-ai-agent/): Use when configuring Cursor, Claude Code, Claude Desktop, Codex, VS Code, or another MCP client
- [Connect Programmatically](/integrations/connect-programmatically/): Use when wiring an MCP-capable framework to `https://mcp.mekodata.ai/mcp` (no Python SDK yet; fuller framework guides under development)

## Examples

- [Enhanced Teaming](/examples/meko-enhances-teaming/): Use when showing handoffs, shared standards, and team memory across agents
- [Traces and Resumability](/examples/trace-and-resume/): Use when showing decision traces, archived conversations, and resumable agent state

## Reference

- [API Keys](/reference/api-keys/): Use when generating, naming, rotating, or revoking `mko_tkn_` keys
- [Meko MCP Server](/reference/mcp-server/): Use when looking up the 23 tools, quotas, and call patterns

## Other

- [Changelog](/changelog/): Use when checking installer (`@yugabytedb/meko-mcp`) or platform release notes
- [Troubleshooting](/troubleshooting/): Use when installs, auth, hooks, or automatic capture fail