Skip to content
Memorg

Quickstart

From pip install to recall in five minutes.

Memorg runs in your process against a single SQLite file. Install it, point it at a file, store a few exchanges, and call search_context(). That is the whole loop.

  1. Step 1

    Install Memorg

    Install the package from PyPI with pip. Memorg targets Python 3.11+.

  2. Step 2

    Set your OpenAI key

    Export OPENAI_API_KEY so Memorg can embed exchanges and items.

  3. Step 3

    Create a system and a session

    Wire SQLite storage and the USearch vector store into a MemorgSystem, then create a session for a user.

  4. Step 4

    Store and retrieve context

    Record exchanges as the conversation runs, then call search_context() to pull back the blended, budget-trimmed top context.

1 · Install

shell 
# Python 3.11+
pip install memorg

export OPENAI_API_KEY="sk-..."

2 · Store and retrieve

quickstart.py 
import asyncio
from memorg import MemorgSystem
from memorg.storage.sqlite_storage import SQLiteStorageAdapter
from memorg.vector_store.usearch_vector_store import USearchVectorStore
from openai import AsyncOpenAI

async def main():
    system = MemorgSystem(
        storage=SQLiteStorageAdapter("memory.db"),
        vector_store=USearchVectorStore("memory.db"),
        openai_client=AsyncOpenAI(),
    )

    # A session is scoped to a user and carries the token budget.
    session = await system.create_session("user_123", {})
    conversation = await system.start_conversation(session.id)

    # Store an exchange as the conversation runs.
    await system.add_exchange(
        conversation.id,
        user="We decided to ship the v2 API next Tuesday.",
        system="Noted — v2 API ships next Tuesday.",
    )

    # Later, recall the relevant, recent, important context — trimmed to budget.
    results = await system.search_context("when are we shipping the API?")
    for item in results:
        print(item)

asyncio.run(main())

3 · Or wire up MCP

Prefer to let an MCP-aware client read and write memory directly? Start the bundled FastMCP server.

shell 
# Expose Memorg to any MCP-aware client (Claude Desktop, Cursor, ...)
python -m memorg.mcp   # starts the FastMCP server

Quickstart FAQ

+ What are the dependencies?

Memorg installs with pip on Python 3.11+. Its dependencies include openai, tiktoken, aiosqlite, numpy, usearch, and fastmcp. There are no native services to run.

+ Do I need a vector database?

No. USearch is embedded in the same SQLite file, so storage and vector search both live in one file you own.

+ Does it work offline?

Storage and vector search are local. Embedding and generation call OpenAI, which requires a network and an OPENAI_API_KEY.

Full API reference and guides live in the docs. New to the concepts? Read how it works or the glossary.

That's the whole loop.

Store exchanges, call search_context(), get scoped and budget-trimmed recall.

Read the docs How it works