Memic Sdk

Memic — Context Engineering SDK

What is Memic?

Memic is a managed context engineering platform. Instead of stuffing raw documents into your LLM's context window (expensive, slow, hits token limits), Memic handles the entire pipeline — document ingestion, chunking, embedding, vector storage — and gives you a single search API that returns only the relevant pieces. It also supports Text2SQL for structured databases, so one API covers both documents and databases.

The problem it solves: AI agents and LLM apps need grounded context from real data. Without Memic, you'd build and maintain your own chunking pipeline, embedding infrastructure, vector database, and query routing. Memic does all of this as a service — upload files, search with one API call, get back ranked chunks with source attribution.

Key capabilities:

• Document search (RAG) — Upload PDFs, DOCX, PPTX, TXT, etc. Memic chunks, embeds, and indexes them. Search returns ranked content with file name, page number, and relevance score.
• Database search (Text2SQL) — Connect PostgreSQL/MySQL. Ask natural language questions, get SQL-generated results back.
• Hybrid search — Single API auto-routes queries to the right source (documents, database, or both).
• Multi-tenant isolation — Each API key is scoped to an org/project/environment. No data leaks between tenants.
• Metadata filters — Filter by reference ID, page range, category, document type.

Your API key auto-resolves all context (org, project, environment) — no IDs needed in API calls.

Coming soon:

• MCP server — Native Model Context Protocol integration so AI agents (OpenClaw, Claude Code, etc.) can call Memic as a tool directly.
• Context compaction — Upload raw agent session logs or MEMORY.md files. Memic summarizes, compresses, and indexes them so agents can retrieve past context without re-loading full session history.
• Bulk context injection — Ingest entire knowledge bases (session JSONL, chat logs, wiki exports) in one call. Memic auto-chunks and indexes for instant search.

When to use this skill: Setting up Memic SDK, uploading documents, searching for context, building RAG pipelines, connecting databases for Text2SQL, debugging integration issues, or reducing LLM token costs by replacing raw context with targeted search.

Quick Start

pip install memic
export MEMIC_API_KEY=mk_your_key_here

from memic import Memic

client = Memic()  # API key auto-resolves org/project/environment

# Upload a document
file = client.upload_file("/path/to/doc.pdf")

# Search — returns only the relevant chunks, not the whole document
results = client.search(query="What are the key findings?", top_k=5)
for r in results:
    print(f"[{r.score:.2f}] {r.file_name} p{r.page_number}: {r.content[:100]}")

First: Understand the Use Case

Ask the developer two questions:

Question 1: Integration Pattern

"How are you planning to use Memic?"

1. Context tool for an AI agent — Memic provides RAG context for an LLM agent (chatbot, copilot, assistant)
2. Deterministic service — Direct search API in your app (no LLM involved)

Question 2: Data Source

"What type of data will you be searching?"

1. Unstructured (Documents) — PDFs, Word docs, text files → semantic vector search
2. Structured (Databases) — PostgreSQL/MySQL → natural language to SQL
3. Hybrid — Both document search and database queries via a single API

Prerequisites

• Python 3.8+
• A Memic account at https://app.memic.ai
• An API key (starts with mk_...)

Step 1: Get API Key

1. Go to https://app.memic.ai → Dashboard → API Keys
2. Click "Create API Key"
3. Copy the key

Important: Each API key is scoped to an organization + project + environment. The SDK auto-resolves this context — you never need to pass IDs.

Step 2: Install & Configure

pip install memic

# .env file
MEMIC_API_KEY=mk_your_api_key_here

Step 3: Verify Setup

from memic import Memic

client = Memic()

# Check what your API key resolves to
print(f"Org: {client.org_id}")
print(f"Project: {client.project_id}")
print(f"Environment: {client.environment_slug}")

# List projects in your org
projects = client.list_projects()
for p in projects:
    print(f"  - {p.name} ({p.id})")

If No Data Found

For documents: Upload via dashboard (https://app.memic.ai → Project → Upload) or SDK (see below).

For databases: Go to https://app.memic.ai → Connectors → Add Connector. Enter your PostgreSQL/MySQL connection details.

Core API Reference

Upload Files

# Upload and wait for processing to complete
file = client.upload_file(
    file_path="/path/to/document.pdf",
    reference_id="lesson_123",       # optional — for external system linking
    metadata={"category": "legal"},  # optional — custom key-value pairs
)
print(f"ID: {file.id}, Status: {file.status}")  # status = "ready" when done

Supported formats: PDF, DOCX, DOC, PPTX, XLSX, TXT, MD, HTML, and more.

Check File Status

file = client.get_file_status(file_id="...")
print(f"Status: {file.status}")
print(f"Processing: {file.status.is_processing}")
print(f"Failed: {file.status.is_failed}")
print(f"Chunks: {file.total_chunks}")

Search Documents (Semantic)

results = client.search(
    query="What are the key findings?",
    top_k=10,
    min_score=0.7,
)

print(f"Found {results.total_results} results in {results.search_time_ms}ms")
for r in results:
    print(f"[{r.score:.2f}] {r.file_name} p{r.page_number}: {r.content[:150]}")

Search with Metadata Filters

from memic import MetadataFilters, PageRange

results = client.search(
    query="contract terms",
    top_k=5,
    filters=MetadataFilters(
        reference_id="contract_2024",              # filter by reference
        page_range=PageRange(gte=1, lte=20),       # pages 1-20 only
        category="legal",                          # by category
    )
)

Available filters:

• reference_id / reference_ids — match file reference IDs
• page_number / page_numbers — exact page match
• page_range — page range with gte/lte
• category — filter by category
• document_type — filter by document type

Search with File Scoping

# Search only within specific files
results = client.search(
    query="revenue figures",
    file_ids=["file-id-1", "file-id-2"],
    top_k=5,
)

Hybrid Search (Documents + Databases)

When you have both documents and database connectors configured, Memic auto-routes queries:

results = client.search(query="Show me top customers by revenue")

# Check how the query was routed
if results.routing:
    print(f"Route: {results.routing.route}")        # "semantic", "structured", or "hybrid"
    print(f"Reason: {results.routing.reasoning}")

# Document results
if results.has_documents:
    for r in results.results.semantic:
        print(f"[Doc] {r.file_name}: {r.content[:100]}")

# Database results (Text2SQL)
if results.has_structured:
    print(f"SQL: {results.routing.sql_generated}")
    for row in results.results.structured.rows:
        print(f"[DB] {row}")

Chat (RAG with built-in LLM)

response = client._request(
    "POST", "/sdk/chat",
    json={"question": "What are the Q4 results?", "top_k": 5, "min_score": 0.5}
)
print(response["answer"])
print(f"Citations: {response['citations']}")
print(f"Model: {response['model']}")

Integration Patterns

Pattern A: Context Tool for AI Agent

Use Memic to inject grounded context into your LLM:

from memic import Memic
from openai import OpenAI  # or anthropic, etc.

memic = Memic()
llm = OpenAI()

def ask_with_context(question: str) -> str:
    # 1. Get relevant context from Memic
    results = memic.search(query=question, top_k=5, min_score=0.6)

    # 2. Format as LLM context
    context = "\n\n".join([
        f"[Source: {r.file_name}, Page {r.page_number}]\n{r.content}"
        for r in results
    ])

    # 3. Generate grounded response
    response = llm.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": f"Answer based on this context:\n\n{context}"},
            {"role": "user", "content": question}
        ]
    )
    return response.choices[0].message.content

answer = ask_with_context("What are the key contract terms?")

Pattern B: OpenClaw / AI Agent Context Optimization

Replace expensive raw-context loading with targeted search to cut token costs:

from memic import Memic

memic = Memic()

# Instead of loading entire documents into context (thousands of tokens),
# search for just the relevant chunks (hundreds of tokens)
results = memic.search(query=user_question, top_k=3, min_score=0.7)

# Only inject what's relevant — typically 90%+ token savings vs raw context
context = "\n".join([r.content for r in results])

Pattern C: Deterministic Search API

Direct integration for app search functionality:

from memic import Memic, MetadataFilters

memic = Memic()

def search_documents(query: str, category: str = None) -> dict:
    filters = MetadataFilters(category=category) if category else None

    results = memic.search(
        query=query,
        top_k=10,
        min_score=0.5,
        filters=filters,
    )

    return {
        "results": [
            {
                "title": r.file_name,
                "snippet": r.content[:300],
                "page": r.page_number,
                "score": r.score,
            }
            for r in results
        ],
        "total": results.total_results,
    }

Debugging

Exception Handling

from memic import MemicError, AuthenticationError, NotFoundError, APIError

try:
    results = client.search(query="test")
except AuthenticationError:
    print("Invalid or expired API key")
except NotFoundError:
    print("Resource not found")
except APIError as e:
    print(f"API error {e.status_code}: {e.message}")
except MemicError as e:
    print(f"SDK error: {e}")

Resources

• SDK: pip install memic | https://pypi.org/project/memic/
• Dashboard: https://app.memic.ai
• GitHub: https://github.com/memic-ai/memic-python