Experimental software

Memorizz is an educational/experimental framework. APIs may change and the project has not undergone security hardening for production workloads.

Memorizz is a Python framework for building memory-augmented AI agents. It provides:

• multiple memory systems (episodic, semantic, procedural, short-term, shared)
• pluggable storage providers (Oracle, MongoDB, filesystem)
• agent builders and application modes (assistant, workflow, deep_research)
• scheduled automations (cron, interval, one-shot) with optional WhatsApp delivery
• optional internet access, sandbox code execution, skills marketplace, and local web UI
• an interactive, Claude-Code-style terminal CLI (memorizz) with persistent memory — see CLI

Key Capabilities

• Persistent memory across sessions and conversations
• Semantic retrieval with embeddings + vector search
• Knowledge base with file/folder ingestion (.pdf, .md, .txt, .csv, .json, …) and configurable chunking (fixed / sentence / paragraph / semantic / custom). Same extractor registry powers the SDK and the local UI's drag-and-drop uploader; see long_term/semantic/README.md.
• Entity memory tools for profile-style facts (entity_memory_lookup / entity_memory_upsert)
• Tool calling with automatic function registration
• Semantic cache to reduce repeat LLM calls
• Prompt-cache-friendly context assembly — stable prefix (frozen system prompt, append-only chunk-evicted history) with all per-turn content at the tail; automatic Anthropic cache_control breakpoints and OpenAI prompt_cache_key routing serve most of each turn's prompt at cached-input rates (see docs/guides/context-efficiency.md)
• Pre-inference deduplication — retrieved memories are exact-hash, similarity (cosine ≥ 0.95), and vs-history deduplicated, then MMR-selected before entering the context window
• Continual learning — repeated successful tool workflows are promoted into reusable learned skills (gated by frequency × success × recency × query diversity, LLM-distilled into validated SKILL.md documents, monitored for drift, and demoted when they stop working). Skills use user-context authority by default; reviewed skills can opt into developer/application authority. Enable with continual_learning=True (see docs/guides/continual-learning.md)
• Multi-agent orchestration with shared blackboard memory
• Context-window telemetry via get_context_window_stats() and per-turn cache metrics (cached_tokens) from get_last_usage()
• Skills marketplace with Vercel Agent Skills and SkillsMP providers
• Scheduled automations via SDK, web UI, or agent conversation (see src/memorizz/automation/README.md)

Installation

Base install:

pip install memorizz

The base install also gives you the interactive memorizz CLI (see CLI) — no extra needed.

Common extras:

pip install "memorizz[oracle]"          # Oracle provider
pip install "memorizz[mongodb]"         # MongoDB provider
pip install "memorizz[filesystem]"      # Local filesystem + FAISS
pip install "memorizz[sandbox-e2b]"     # E2B sandbox
pip install "memorizz[sandbox-daytona]" # Daytona sandbox
pip install "memorizz[ui]"              # Local web UI
pip install "memorizz[huggingface]"     # transformers + sentence-transformers
pip install "memorizz[mlx]"             # Apple-Silicon MLX backend (native arm64 only)
pip install "memorizz[all]"             # Everything

Quick Start (Filesystem Provider)

import os
from pathlib import Path

from memorizz.memagent.builders import MemAgentBuilder
from memorizz.memory_provider import FileSystemConfig, FileSystemProvider

os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

provider = FileSystemProvider(
    FileSystemConfig(
        root_path=Path("~/.memorizz").expanduser(),
        embedding_provider="openai",
        embedding_config={"model": "text-embedding-3-small"},
    )
)

agent = (
    MemAgentBuilder()
    .with_instruction("You are a helpful assistant with persistent memory.")
    .with_memory_provider(provider)
    .with_llm_config(
        {
            "provider": "openai",
            "model": "gpt-4o-mini",
            "api_key": os.environ["OPENAI_API_KEY"],
        }
    )
    .with_semantic_cache(enabled=True, threshold=0.85)
    .build()
)

print(agent.run("Hi, my name is Leah and I work on payments systems."))
print(agent.run("What did I tell you about my work?"))

stats = agent.get_context_window_stats()
print(stats)

Building a multi-user application? Pass user_id to isolate memory per end-user — one agent can serve every tenant in your app. See the Multi-Tenant Guide for the full contract.

agent.run("Remember my favorite color is purple.", user_id="alice")
agent.run("What's my favorite color?", user_id="bob")  # won't see alice's data

Continual Learning and Reviewed Skill Authority

Continual learning is provider-independent across filesystem, MongoDB, and Oracle. Workflow memory remains the audit and outcome-evidence store; automatic prompt retrieval does not replay raw workflows. Matching active skills are retrieved from Skillbox instead.

from memorizz import MemAgent

agent = MemAgent(
    model=model,
    memory_provider=provider,
    tools=tools,
    continual_learning=True,
    continual_learning_config={
        "require_shadow": True,
        "skill_injection_role": "developer",  # or "user" (default)
    },
)

developer is deliberately rejected unless require_shadow=True: generated instructions must be validated, reviewed, and explicitly activated before gaining application-level authority. The official OpenAI API receives a developer message; Anthropic receives the reviewed instructions through its top-level system parameter. System policy and current tool/database facts still win. Legacy skills remain at user authority.

The local UI exposes both authority options and shows each skill's persisted role. See the Continual Learning guide for promotion, review, provider mapping, Oracle migration, and the three-arm token/latency/accuracy notebook evaluation.

Local LLMs (Gemma 4, Llama, Qwen, …)

Memorizz speaks several local-LLM backends so you can run an entire agent loop without sending tokens to a third-party API. The local UI exposes all of these in the agent form's Provider dropdown.

Gemma 4 is gated. Accept the license once at huggingface.co/google/gemma-4-E2B-it (or the variant you want) and set HF_TOKEN in Settings before pulling. The agent form surfaces this hint inline whenever a gated repo is selected.

Path A — Hugging Face Transformers (works everywhere)

pip install "memorizz[huggingface]"
export HF_TOKEN=hf_...

# In the UI: Agents → New → Provider = HuggingFace,
#           Model = google/gemma-4-E2B-it
# Or via the SDK:

from memorizz.memagent.builders import MemAgentBuilder

agent = (
    MemAgentBuilder()
    .with_memory_provider(provider)
    .with_llm_config({
        "provider": "huggingface",
        "model": "google/gemma-4-E2B-it",
        "max_new_tokens": 512,
        "temperature": 0.7,
    })
    .build()
)

The HF provider auto-detects offline mode (sets local_files_only=True when HF_HUB_OFFLINE=1 is set or huggingface.co is unreachable) and streams tokens via TextIteratorStreamer.

Path B — MLX (Google's recommendation for Apple Silicon)

Requires a native arm64 Python for the memorizz process itself. pip install memorizz[mlx] will fail on Rosetta x86_64 environments. If your memorizz env is x86_64, skip to Path B-sidecar below — it runs MLX in a separate arm64 process and works regardless.

In-process MLX (best when memorizz's own Python is arm64):

pip install "memorizz[mlx]"

# In the UI: Provider = MLX (Apple Silicon),
#           Model = mlx-community/gemma-4-E2B-it-4bit

agent = (
    MemAgentBuilder()
    .with_memory_provider(provider)
    .with_llm_config({
        "provider": "mlx",
        "model": "mlx-community/gemma-4-E2B-it-4bit",
        "max_new_tokens": 512,
    })
    .build()
)

Pre-quantized weights live under mlx-community/* — they reuse the standard ~/.cache/huggingface/hub cache, so the playground's "Available offline" indicator covers them too.

Path B-sidecar — MLX through mlx_lm.server (works from x86_64 too)

If your primary memorizz env is x86_64 (Rosetta-emulated conda envs are common on Macs with an Intel-era Anaconda install), run MLX in its own small arm64 venv and let memorizz talk to it via OpenAI-compatible HTTP (this reuses Path C plumbing — same OpenAI provider with base_url):

# One-time, in a native arm64 Python (system /usr/bin/python3 works):
/usr/bin/python3 -m venv ~/.mlx_serve
~/.mlx_serve/bin/pip install mlx-lm

# Each session — pick the model and port:
~/.mlx_serve/bin/python -m mlx_lm.server \
    --model mlx-community/gemma-4-E2B-it-4bit \
    --port 8080

In the UI: Provider = Local OpenAI-compatible, pick any mlx-community/* entry (the dropdown groups them under "MLX — mlx_lm.server"), leave the base URL as http://127.0.0.1:8080/v1. The hint in the agent form auto-detects the mlx-community/ prefix and shows the correct startup command.

Path C — llama.cpp / LM Studio (OpenAI-compatible)

Run an OpenAI-compatible server externally, then point memorizz at it. The OpenAI provider accepts a base_url, so the agent talks to your local server through the same code path as the real OpenAI API.

brew install llama.cpp                                    # or build from source
llama-server -hf ggml-org/gemma-4-E2B-it-GGUF \
             --port 8080 --jinja

# In the UI: Provider = Local OpenAI-compatible (llama.cpp / LM Studio)
#           Model = whatever the server exposes at /v1/models
#           Base URL = http://127.0.0.1:8080/v1

agent = (
    MemAgentBuilder()
    .with_memory_provider(provider)
    .with_llm_config({
        "provider": "openai",
        "model": "gemma-4-e2b",                # whatever your server reports
        "base_url": "http://127.0.0.1:8080/v1", # llama.cpp default
    })
    .build()
)

LM Studio defaults to http://127.0.0.1:1234/v1. vLLM and any other /v1/chat/completions-compatible server work the same way.

Oracle Setup (Optional)

If you want Oracle AI Database as the backing store:

memorizz oracle install
memorizz oracle setup

Then configure ORACLE_USER, ORACLE_PASSWORD, ORACLE_DSN, and your LLM credentials. Full setup details are in SETUP.md.

For multi-client consistency (UI + notebooks), you can set shared embedding defaults:

export MEMORIZZ_DEFAULT_EMBEDDING_PROVIDER=openai
export MEMORIZZ_DEFAULT_EMBEDDING_MODEL=text-embedding-3-small
export MEMORIZZ_DEFAULT_EMBEDDING_DIMENSIONS=1536

Application Modes

ApplicationMode presets automatically enable different memory stacks:

• assistant: conversation, long-term, personas, entity memory, short-term, summaries
• workflow: workflow memory, toolbox, long-term, short-term, summaries
• deep_research: toolbox, shared memory, long-term, short-term, summaries

Example:

import os

from memorizz.enums import ApplicationMode
from memorizz.memagent.builders import MemAgentBuilder

llm_config = {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "api_key": os.environ["OPENAI_API_KEY"],
}

agent = (
    MemAgentBuilder()
    .with_application_mode(ApplicationMode.DEEP_RESEARCH)
    .with_memory_provider(provider)
    .with_llm_config(llm_config)
    .build()
)

Internet Access (Deep Research)

Deep Research agents can attach internet providers and expose internet_search / open_web_page tools.

import os

from memorizz.internet_access import TavilyProvider
from memorizz.memagent.builders import create_deep_research_agent

llm_config = {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "api_key": os.environ["OPENAI_API_KEY"],
}

internet_provider = TavilyProvider(api_key=os.environ["TAVILY_API_KEY"])

agent = (
    create_deep_research_agent(internet_provider=internet_provider)
    .with_memory_provider(provider)
    .with_llm_config(llm_config)
    .build()
)

results = agent.search_internet("latest vector database benchmark")

Sandbox Code Execution

Attach a sandbox provider to enable execute_code, sandbox_write_file, and sandbox_read_file tools.

import os

from memorizz.memagent import MemAgent

llm_config = {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "api_key": os.environ["OPENAI_API_KEY"],
}

agent = MemAgent(
    llm_config=llm_config,
    memory_provider=provider,
    sandbox_provider="e2b",  # or "daytona" / "graalpy"
)

print(agent.execute_code("print(2 ** 16)"))

Skills Marketplace

MemAgents can search and use agent skills from external marketplaces at runtime. Two providers are available:

• Vercel Agent Skills (vercel) – searches the open skills.sh ecosystem and fetches SKILL.md instruction files from any GitHub repository. No API key required (set GITHUB_TOKEN for better rate limits).
• SkillsMP (skillsmp) – searches skillsmp.com. Requires SKILLSMP_API_KEY.

Vercel Agent Skills

When enabled, the agent receives two tools:

• vercel_skills_search(q) – search the skills ecosystem by keyword
• vercel_skill_fetch(repo) – fetch a skill's instructions from a GitHub repo (owner/repo or full URL)

The agent reads the fetched SKILL.md instructions and follows them to complete the task.

from memorizz.memagent import MemAgent

agent = MemAgent(
    llm_config=llm_config,
    memory_provider=provider,
    skills_marketplace_provider="vercel",
)

# The agent can now search for and apply Vercel Agent Skills
print(agent.run("Build a Next.js app with best practices"))

Users can also pass a specific repo directly. The agent fetches the SKILL.md and applies the instructions:

agent = MemAgent(
    llm_config=llm_config,
    memory_provider=provider,
    skills_marketplace_provider="vercel",
)

print(agent.run("Use the skill from vercel/ai-chatbot to set up a chatbot"))

The local web UI includes a dedicated Vercel Skills page for browsing, searching, and previewing skill instructions. Enable the Vercel provider on any agent via the Skills Marketplace dropdown in the agent creation/edit form.

Multi-Agent Deep Research Workflow

from memorizz.memagent.orchestrators import DeepResearchWorkflow

workflow = DeepResearchWorkflow.from_config(
    memory_provider=provider,
    delegate_instructions=[
        "Financial researcher: collect metrics and citations.",
        "Risk analyst: identify key downside scenarios.",
    ],
)

report = workflow.run("Analyze the last 3 years of cloud infrastructure trends.")
print(report)

CLI

Memorizz ships an interactive, Claude-Code-style terminal agent with persistent memory.

Install (pick one):

pip install memorizz                                   # if you have Python 3.10+
uv tool install --python 3.12 memorizz                 # isolated tool, no system Python needed
npm install -g memorizz                                # bootstraps uv under the hood
curl -fsSL https://raw.githubusercontent.com/RichmondAlake/memorizz/main/install.sh | sh

Then just run memorizz:

memorizz                       # interactive REPL (memory persists across launches)
memorizz --code                # enable coding tools (read/write files + commands)
memorizz run "your prompt"     # one-shot, prints the reply
memorizz ui                    # start the local web UI (requires [ui])

With no API key and a running Ollama daemon it runs a 100% local stack (Ollama LLM + embeddings + on-disk memory). Inside the REPL, /help lists 20+ slash commands (/model, /code, /persona, /memory, /forget, /clear, /ingest, /ui, …).

See the CLI Guide for the full reference.

Database/admin helpers:

memorizz oracle install             # start Oracle container helper
memorizz oracle setup               # initialize Oracle schema/user

Examples

• examples/single_agent/memagent_local_oracle.ipynb
• examples/single_agent/memagent_remote_oracle.ipynb
• examples/deep_research/deep_research_memagent.ipynb
• examples/sandbox/memagent_e2b_sandbox.ipynb
• examples/sandbox/memagent_daytona_sandbox.ipynb
• examples/sandbox/memagent_graalpy_sandbox.ipynb
• examples/automations/automations_guide.ipynb
• examples/continual_learning/continual_learning_guide.ipynb
• examples/model_providers/openai_provider.ipynb
• examples/model_providers/anthropic_provider.ipynb
• examples/model_providers/ollama_provider.ipynb
• examples/model_providers/compare_providers.ipynb

Documentation

• Docs source: docs/
• Local preview: make docs-serve (or mkdocs serve)
• Architecture notes: src/memorizz/MEMORY_ARCHITECTURE.md

License

PolyForm Noncommercial 1.0.0. See LICENSE and NOTICE.