MemoryBrain
===========

Long-term memory library for AI assistants, chatbots, and autonomous agents.
Stores memories in a local SQLite database with intelligent ranked retrieval.

Requirements
------------
- Python 3.10 or newer
- No third-party runtime dependencies

Installation
------------
    pip install memorybrain

Or install from source:

    pip install .

Quick Start
-----------
    from memorybrain import MemoryBrain

    brain = MemoryBrain()

    brain.remember(
        "User likes Flutter development",
        tags=["flutter", "programming"],
        importance=10,
    )

    results = brain.recall("What framework does the user like?")
    for memory in results:
        print(memory.text)

    matches = brain.search("Flutter")
    print(matches)

    print(brain.stats())

API Overview
------------
remember(text, tags=None, importance=5)
    Store a new memory. Returns a Memory object.

recall(query, limit=10)
    Retrieve memories ranked for a natural-language query.

search(query, limit=10)
    Search memories by keyword relevance.

forget(memory_id)
    Delete a memory by ID. Returns True if deleted.

export("memories.json")
    Export all memories to a JSON file.

import_file("memories.json")
    Import memories from JSON (upsert by ID).

stats()
    Return statistics:
    - total_memories
    - most_common_tags (list of {tag, count})
    - database_size_bytes

Custom Database Path
--------------------
    brain = MemoryBrain(db_path="./data/my_memories.db")

Default location: ~/.memorybrain/memories.db

Build and Publish to PyPI
-------------------------
Install build tools:

    pip install wheel twine build

Build source distribution and wheel:

    python setup.py sdist bdist_wheel

Or using the modern build frontend:

    python -m build

Validate packages:

    twine check dist/*

Upload to PyPI (requires PyPI account and API token):

    twine upload dist/*

Test upload to TestPyPI first:

    twine upload --repository testpypi dist/*

License
-------
MIT License — see LICENSE.txt
