redis-memory 0.3.4

An object that persists in Redis. Works across instances and works seamlessly through magic functions.

🗄️ redis-memory

A production-ready Python class for seamless, multiprocessing-safe, persistent key-value storage using Redis as a backend. If Redis is unavailable, values are cached locally and queued for syncing when Redis comes back online. All values are serialized as JSON, and you interact with it using natural Python attribute access.

Purpose

The intention is to use this with agentic workflows deployed as microservices, allowing for multiple instances of the same pod to share their state.

✨ Features

• 🔄 Multiprocessing-safe: All processes share the same state via Redis.
• 🧠 Pythonic API: Set and get attributes as if they were regular object properties.
• 🕰️ Persistence: Values survive process restarts and context blocks.
• 🚦 Resilient: If Redis is down, changes are queued and flushed when it returns.
• 🧩 Customizable: Prefixes and conversation IDs for namespacing.
• 🧵 Background sync: Queued changes are flushed automatically in the background.

🚀 Quickstart

pip install redis-memory

from redis_memory import Memory

mem = Memory()
mem.answer = 42
print(mem.answer)  # 42

# Across processes or instances:
mem2 = Memory()
print(mem2.answer)  # 42

mem.settings = {"theme": "dark", "volume": 0.75}
print(mem.settings)  # {'theme': 'dark', 'volume': 0.75}

🧑‍💻 Context Management

You can use Memory as a context manager for automatic resource handling:

with Memory() as memory:
    memory.session = "active"
    print(memory.session)  # "active"

# Later, in a new context:
with Memory() as memory:
    print(memory.session)  # "active"

� Auto-Synced Collections

Lists and dictionaries are automatically wrapped as SyncedList and SyncedDict, which sync changes to Redis immediately:

mem = Memory()
mem.items = [1, 2, 3]
mem.items.append(4)  # Automatically syncs to Redis

mem2 = Memory()
print(mem2.items)  # [1, 2, 3, 4]

mem.config = {"theme": "dark"}
mem.config["lang"] = "en"  # Automatically syncs to Redis
print(mem2.config)  # {'theme': 'dark', 'lang': 'en'}

Nested structures work too:

mem.data = {"user": {"preferences": {"color": "blue"}}}
mem.data["user"]["preferences"]["color"] = "red"  # Syncs!

Converting to Plain Python Types

For libraries that need plain Python objects (serialization, pickling, etc.):

mem.items = [1, 2, 3]
plain_list = mem.items.aslist()  # Returns regular list

mem.config = {"key": "value"}
plain_dict = mem.config.asdict()  # Returns regular dict

# Now you can pickle, deepcopy, or pass to external libraries
import pickle
pickle.dump(plain_list, file)  # Works!

🗂️ Namespacing

By default, redis-memory uses memory: as its Redis prefix.

Set that with REDIS_PREFIX:

REDIS_PREFIX="my_service_state:"

from redis_memory import Memory

mem = Memory()
mem.state = {"step": 1}
print(mem.state)  # {'step': 1}

Agents

Use the specific class ConversationMemory as an agent memory:

# TODO: Expand with a real conversation object and/or LiteLLM

from redis_memory import ConversationMemory

conversation_id = uuid()

mem = ConversationMemory(conversation_id=conversation_id)
mem.messages = messages  # The messages payload to an LLM.

⚙️ Environment Variables

• REDIS_HOST: Redis server hostname (default: redis)
• REDIS_PORT: Redis server port (default: 6379)
• REDIS_PREFIX: Key prefix (default: memory:)

🛠️ Development

🐳 Docker/Devcontainer

• Clone the repo.
• You can use VS Code Dev Containers for an instant dev environment.
• Or, just run tests in Docker—no setup needed!

🧪 Running Tests

With a Development Container: Open in VS Code, and start the development container. You do not need to install anything other than VS Code and docker. (Shift/Cmd + P and check under ``Dev Containers'')

Run the two VS code tasks, test and reformat, before making a PR. These are the same as the tests that will run on the CI/CD pipeline.

Without Anything: Just write the code, and add your unit tests. (Test-Driven Development) Run the following command:

docker-compose up --build --remove-orphans --force-recreate --abort-on-container-exit --exit-code-from test

The only requirement is docker.

Virtual Env: I did not add support for the Python venv. However, all of the requirements are captured in pyproject.toml. You should be able to use the following commands to set up a venv with all of the requirements.

python -m venv .venv
source .venv/bin/activate       # macOS/Linux
.venv\Scripts\activate          # Windows

pip install --upgrade pip
pip install .
pip install .[test]
pip install .[dev]

🤝 Contributing

• PRs are welcome! No special permissions required.
• All you need is Docker (or a devcontainer).
• Please ensure all tests pass before submitting your PR.

📚 License

MIT

---

Made with ❤️ and Redis.