MemoBox

MemoBox is a tiny, local, persistent memory store for Python programs.

It uses a JSON file, so there is no database server, account, API key, or setup required.

Install

pip install MemoBox

Quick start

from MemoBox import Brain

brain = Brain()

brain.remember("username", "sam")
brain.remember("theme", "dark")

print(brain.recall("username"))
# sam

print(brain.exists("theme"))
# True

brain.forget("theme")

Categories

brain.remember("python", "PyPI", category="interests")
brain.remember("robotics", "Arduino", category="interests")

print(brain.category("interests"))

Search

brain.remember("project", "MemoBox")
brain.remember("language", "Python")

print(brain.search("python"))

Custom storage path

brain = Brain("my_memory.json")

By default MemoBox stores data in .MemoBox/memory.json in the current working directory.

Expiring memory

You can store a value with an expiration time:

brain.remember("temporary", "hello", expires="1h")

Supported units:

• s — seconds
• m — minutes
• h — hours
• d — days

Examples: 30s, 10m, 2h, 7d.

API

Brain(path=None)

Creates a memory store.

remember(key, value, category=None, expires=None)

Stores or replaces a value.

recall(key, default=None)

Returns a value, or default if it does not exist.

forget(key)

Removes a key. Returns True if it existed.

exists(key)

Checks whether a non-expired key exists.

all(category=None)

Returns all stored values, optionally filtered by category.

category(name)

Returns all values in a category.

search(query)

Searches keys, categories, and stringified values.

clear(category=None)

Clears everything, or only one category.

Example

from MemoBox import Brain

brain = Brain()

brain.remember("username", "sam")
brain.remember("editor", "VS Code", category="tools")
brain.remember("language", "Python", category="tools")

print(brain.recall("username"))
print(brain.category("tools"))
print(brain.search("python"))

Development

Clone the repository and install the package in editable mode:

pip install -e ".[dev]"

Run tests:

pytest

Build the package:

python -m build

License

MIT