Metadata-Version: 2.5
Name: memobox
Version: 0.1.0
Summary: A tiny, local, persistent memory store for Python projects.
Project-URL: Homepage, https://github.com/yourusername/memobox
Project-URL: Repository, https://github.com/yourusername/memobox
Project-URL: Issues, https://github.com/yourusername/memobox/issues
Author: memobox Contributors
License: MIT
License-File: LICENSE
Keywords: json,key-value,memory,persistence,storage,utility
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install MemoBox
```

## Quick start

```python
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

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

print(brain.category("interests"))
```

## Search

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

print(brain.search("python"))
```

## Custom storage path

```python
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:

```python
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

```python
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:

```bash
pip install -e ".[dev]"
```

Run tests:

```bash
pytest
```

Build the package:

```bash
python -m build
```

## License

MIT
