memorybrain 1.0.0__tar.gz

memorybrain-1.0.0/Changelog.txt

@@ -0,0 +1,14 @@
+Changelog
+=========
+
+All notable changes to memorybrain are documented in this file.
+
+[1.0.0] - 2026-06-03
+--------------------
+- Initial PyPI release
+- MemoryBrain class with remember, recall, search, forget
+- SQLite storage backend (automatic local database)
+- Memory ranking by relevance, importance, and recency
+- Export and import memories as JSON
+- Statistics: total memories, most common tags, database size
+- Python 3.10+ support, zero runtime dependencies

memorybrain-1.0.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MemoryBrain Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memorybrain-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.txt
+include Changelog.txt
+include LICENSE.txt
+include requirements.txt
+recursive-include memorybrain *.py

memorybrain-1.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: memorybrain
+Version: 1.0.0
+Summary: Long-term memory library for AI assistants and agents
+Home-page: https://github.com/memorybrain/memorybrain
+Author: MemoryBrain Contributors
+Author-email: memorybrain@example.com
+License: MIT
+Project-URL: Source, https://github.com/memorybrain/memorybrain
+Project-URL: Tracker, https://github.com/memorybrain/memorybrain/issues
+Keywords: ai memory agents llm chatbot sqlite
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/plain
+License-File: LICENSE.txt
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+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
+
+
+MIT License
+
+Copyright (c) 2026 MemoryBrain Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memorybrain-1.0.0/README.txt

@@ -0,0 +1,101 @@
+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

memorybrain-1.0.0/memorybrain/__init__.py

@@ -0,0 +1,20 @@
+"""
+memorybrain — long-term memory for AI assistants and agents.
+
+Example::
+
+    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?")
+"""
+
+from memorybrain.brain import MemoryBrain
+
+__version__ = "1.0.0"
+__all__ = ["MemoryBrain", "__version__"]

memorybrain-1.0.0/memorybrain/brain.py

@@ -0,0 +1,166 @@
+"""MemoryBrain — main public API."""
+
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+from typing import Any
+
+from memorybrain.ranking import RankWeights, rank_memories
+from memorybrain.search import compute_relevance
+from memorybrain.storage import Memory, SQLiteStorage, utc_now
+
+
+class MemoryBrain:
+    """
+    Long-term memory for AI assistants and agents.
+
+    Stores memories in a local SQLite database with ranked recall and search.
+    """
+
+    def __init__(
+        self,
+        db_path: str | Path | None = None,
+        rank_weights: RankWeights | None = None,
+    ) -> None:
+        self._storage = SQLiteStorage(db_path)
+        self._rank_weights = rank_weights
+        self._lock = threading.RLock()
+
+    def remember(
+        self,
+        text: str,
+        *,
+        tags: list[str] | None = None,
+        importance: float = 5.0,
+        metadata: dict[str, Any] | None = None,
+    ) -> Memory:
+        """
+        Store a new memory.
+
+        Args:
+            text: Memory content.
+            tags: Optional list of tags.
+            importance: Priority from 0 to 10 (default 5).
+            metadata: Optional extra key-value data.
+
+        Returns:
+            The stored Memory instance.
+        """
+        with self._lock:
+            memory = Memory(
+                text=text,
+                tags=tags or [],
+                importance=importance,
+                metadata=metadata or {},
+            )
+            return self._storage.add(memory)
+
+    def recall(self, query: str, limit: int = 10) -> list[Memory]:
+        """
+        Retrieve memories ranked for a natural-language query.
+
+        Uses relevance, importance, and recency scoring.
+        """
+        return self._retrieve(query, limit=limit, min_relevance=0.0)
+
+    def search(self, query: str, limit: int = 10) -> list[Memory]:
+        """
+        Search memories by keyword relevance.
+
+        Slightly stricter pre-filter than recall (any token match required when
+        query has tokens).
+        """
+        tokens = query.strip()
+        min_rel = 0.01 if tokens else 0.0
+        return self._retrieve(query, limit=limit, min_relevance=min_rel)
+
+    def _retrieve(self, query: str, limit: int, min_relevance: float) -> list[Memory]:
+        with self._lock:
+            candidates = self._storage.list_all()
+            if not candidates:
+                return []
+            ranked = rank_memories(
+                query,
+                candidates,
+                weights=self._rank_weights,
+                min_relevance=min_relevance,
+            )
+            if not ranked and query.strip():
+                ranked = rank_memories(
+                    query,
+                    candidates,
+                    weights=self._rank_weights,
+                    min_relevance=0.0,
+                )
+            top = ranked[:limit]
+            now = utc_now()
+            for memory, _ in top:
+                memory.access_count += 1
+                memory.metadata["last_accessed"] = now.isoformat()
+                self._storage.update(memory)
+            return [m for m, _ in top]
+
+    def forget(self, memory_id: str) -> bool:
+        """Delete a memory by ID."""
+        with self._lock:
+            return self._storage.delete(memory_id)
+
+    def get(self, memory_id: str) -> Memory | None:
+        """Fetch a single memory by ID."""
+        with self._lock:
+            return self._storage.get(memory_id)
+
+    def export(self, path: str | Path) -> int:
+        """
+        Export all memories to a JSON file.
+
+        Returns:
+            Number of memories exported.
+        """
+        with self._lock:
+            records = self._storage.export_records()
+            path = Path(path)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(json.dumps(records, indent=2), encoding="utf-8")
+            return len(records)
+
+    def import_file(self, path: str | Path) -> int:
+        """
+        Import memories from a JSON file (upsert by ID).
+
+        Returns:
+            Number of memories imported.
+        """
+        with self._lock:
+            path = Path(path)
+            records = json.loads(path.read_text(encoding="utf-8"))
+            if not isinstance(records, list):
+                raise ValueError("Import file must contain a JSON array of memories")
+            return self._storage.import_records(records)
+
+    def stats(self) -> dict[str, Any]:
+        """
+        Return memory statistics.
+
+        Returns:
+            dict with total_memories, most_common_tags, database_size_bytes
+        """
+        with self._lock:
+            total = self._storage.count()
+            tag_counts = self._storage.tag_counts()
+            sorted_tags = sorted(tag_counts.items(), key=lambda x: (-x[1], x[0]))
+            most_common = [
+                {"tag": tag, "count": count} for tag, count in sorted_tags[:10]
+            ]
+            return {
+                "total_memories": total,
+                "most_common_tags": most_common,
+                "database_size_bytes": self._storage.db_file_size_bytes(),
+            }
+
+    @property
+    def db_path(self) -> Path:
+        """Path to the SQLite database file."""
+        return self._storage.db_path

memorybrain-1.0.0/memorybrain/ranking.py

@@ -0,0 +1,88 @@
+"""Memory ranking by relevance, importance, and recency."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from memorybrain.search import compute_relevance
+from memorybrain.storage import Memory, utc_now
+
+
+@dataclass
+class RankWeights:
+    """Weights for composite memory ranking."""
+
+    relevance: float = 0.5
+    importance: float = 0.3
+    recency: float = 0.2
+
+    def normalized(self) -> RankWeights:
+        total = self.relevance + self.importance + self.recency
+        if total <= 0:
+            return RankWeights(1 / 3, 1 / 3, 1 / 3)
+        return RankWeights(
+            relevance=self.relevance / total,
+            importance=self.importance / total,
+            recency=self.recency / total,
+        )
+
+
+def recency_score(memory: Memory, now: datetime, half_life_days: float = 30.0) -> float:
+    """Exponential decay score based on memory age."""
+    ts = memory.timestamp
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+    age_days = max(0.0, (now - ts).total_seconds() / 86400.0)
+    return math.exp(-age_days / half_life_days)
+
+
+def importance_score(memory: Memory) -> float:
+    """Normalize importance to [0, 1]."""
+    return memory.importance / 10.0
+
+
+def score_memory(
+    memory: Memory,
+    relevance: float,
+    now: datetime | None = None,
+    weights: RankWeights | None = None,
+) -> float:
+    """Compute weighted composite score for a memory."""
+    w = (weights or RankWeights()).normalized()
+    now = now or utc_now()
+    rec = recency_score(memory, now)
+    imp = importance_score(memory)
+    return w.relevance * relevance + w.importance * imp + w.recency * rec
+
+
+def rank_memories(
+    query: str,
+    memories: list[Memory],
+    weights: RankWeights | None = None,
+    min_relevance: float = 0.0,
+) -> list[tuple[Memory, float]]:
+    """
+    Rank memories by composite score.
+
+    Returns list of (memory, score) tuples sorted descending by score.
+    """
+    now = utc_now()
+    scored: list[tuple[Memory, float]] = []
+    for memory in memories:
+        rel = compute_relevance(query, memory)
+        if rel < min_relevance:
+            continue
+        total = score_memory(memory, rel, now=now, weights=weights)
+        scored.append((memory, total))
+    scored.sort(
+        key=lambda item: (
+            -item[1],
+            -item[0].importance,
+            -item[0].timestamp.timestamp(),
+        )
+    )
+    return scored

memorybrain-1.0.0/memorybrain/search.py

@@ -0,0 +1,103 @@
+"""Keyword search and relevance scoring."""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+from memorybrain.storage import Memory
+
+_TOKEN_RE = re.compile(r"[a-z0-9]+", re.IGNORECASE)
+_STOPWORDS = frozenset(
+    {
+        "a",
+        "an",
+        "the",
+        "is",
+        "are",
+        "was",
+        "were",
+        "be",
+        "been",
+        "being",
+        "have",
+        "has",
+        "had",
+        "do",
+        "does",
+        "did",
+        "will",
+        "would",
+        "could",
+        "should",
+        "may",
+        "might",
+        "must",
+        "can",
+        "to",
+        "of",
+        "in",
+        "for",
+        "on",
+        "with",
+        "at",
+        "by",
+        "from",
+        "as",
+        "what",
+        "which",
+        "who",
+        "whom",
+        "this",
+        "that",
+        "these",
+        "those",
+        "and",
+        "but",
+        "or",
+        "if",
+        "user",
+        "like",
+        "likes",
+        "does",
+    }
+)
+
+
+def tokenize(text: str) -> list[str]:
+    """Extract lowercase alphanumeric tokens, skipping stopwords."""
+    tokens = [m.group(0).lower() for m in _TOKEN_RE.finditer(text)]
+    return [t for t in tokens if t not in _STOPWORDS and len(t) > 1]
+
+
+def relevance_score(query: str, text: str, tags: Iterable[str] | None = None) -> float:
+    """
+    Score relevance in [0, 1] based on query token overlap with text and tags.
+    """
+    query_tokens = set(tokenize(query))
+    if not query_tokens:
+        return 0.0
+    text_tokens = set(tokenize(text))
+    tag_tokens: set[str] = set()
+    if tags:
+        for tag in tags:
+            tag_tokens.add(tag.lower().strip())
+            tag_tokens.update(tokenize(tag))
+    matched = len(query_tokens & (text_tokens | tag_tokens))
+    return min(1.0, matched / len(query_tokens))
+
+
+def compute_relevance(query: str, memory: Memory) -> float:
+    """Compute relevance score for a memory."""
+    return relevance_score(query, memory.text, memory.tags)
+
+
+def filter_candidates(
+    memories: list[Memory],
+    query: str,
+    min_relevance: float = 0.0,
+) -> list[Memory]:
+    """Return memories meeting minimum relevance threshold."""
+    if min_relevance <= 0:
+        return list(memories)
+    return [m for m in memories if compute_relevance(query, m) >= min_relevance]

memorybrain-1.0.0/memorybrain/storage.py

@@ -0,0 +1,255 @@
+"""SQLite storage backend for MemoryBrain."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def utc_now() -> datetime:
+    """Return current UTC datetime."""
+    return datetime.now(timezone.utc)
+
+
+def normalize_tags(tags: list[str] | None) -> list[str]:
+    """Normalize tags to lowercase stripped unique sorted list."""
+    if not tags:
+        return []
+    return sorted({t.strip().lower() for t in tags if t.strip()})
+
+
+@dataclass
+class Memory:
+    """A single stored memory entry."""
+
+    text: str
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: datetime = field(default_factory=utc_now)
+    tags: list[str] = field(default_factory=list)
+    importance: float = 5.0
+    access_count: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.tags = normalize_tags(self.tags)
+        self.importance = max(0.0, min(10.0, float(self.importance)))
+        if self.timestamp.tzinfo is None:
+            self.timestamp = self.timestamp.replace(tzinfo=timezone.utc)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize memory to a JSON-compatible dict."""
+        return {
+            "id": self.id,
+            "text": self.text,
+            "timestamp": self.timestamp.isoformat(),
+            "tags": self.tags,
+            "importance": self.importance,
+            "access_count": self.access_count,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Memory:
+        """Deserialize memory from a dict."""
+        ts = data.get("timestamp")
+        if isinstance(ts, str):
+            timestamp = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        elif isinstance(ts, datetime):
+            timestamp = ts
+        else:
+            timestamp = utc_now()
+        return cls(
+            id=str(data.get("id", str(uuid.uuid4()))),
+            text=str(data["text"]),
+            timestamp=timestamp,
+            tags=data.get("tags", []),
+            importance=float(data.get("importance", 5.0)),
+            access_count=int(data.get("access_count", 0)),
+            metadata=dict(data.get("metadata", {})),
+        )
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS memories (
+    id TEXT PRIMARY KEY,
+    text TEXT NOT NULL,
+    timestamp TEXT NOT NULL,
+    tags TEXT NOT NULL,
+    importance REAL NOT NULL,
+    access_count INTEGER DEFAULT 0,
+    metadata TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_memories_timestamp ON memories(timestamp);
+"""
+
+
+def default_db_path() -> Path:
+    """Default SQLite database path."""
+    return Path.home() / ".memorybrain" / "memories.db"
+
+
+class SQLiteStorage:
+    """Thread-safe SQLite storage for memories."""
+
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        path = Path(db_path).expanduser() if db_path else default_db_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._db_path = path
+        self._lock = threading.RLock()
+        self._init_db()
+
+    @property
+    def db_path(self) -> Path:
+        return self._db_path
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(self._db_path), check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _init_db(self) -> None:
+        with self._lock:
+            conn = self._connect()
+            try:
+                conn.executescript(_SCHEMA)
+                conn.commit()
+            finally:
+                conn.close()
+
+    def _row_to_memory(self, row: sqlite3.Row) -> Memory:
+        return Memory(
+            id=row["id"],
+            text=row["text"],
+            timestamp=datetime.fromisoformat(row["timestamp"].replace("Z", "+00:00")),
+            tags=json.loads(row["tags"]),
+            importance=float(row["importance"]),
+            access_count=int(row["access_count"] or 0),
+            metadata=json.loads(row["metadata"] or "{}"),
+        )
+
+    def _memory_to_row(self, memory: Memory) -> tuple[Any, ...]:
+        return (
+            memory.id,
+            memory.text,
+            memory.timestamp.isoformat(),
+            json.dumps(memory.tags),
+            memory.importance,
+            memory.access_count,
+            json.dumps(memory.metadata),
+        )
+
+    def add(self, memory: Memory) -> Memory:
+        with self._lock:
+            conn = self._connect()
+            try:
+                conn.execute(
+                    """
+                    INSERT INTO memories (
+                        id, text, timestamp, tags, importance, access_count, metadata
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?)
+                    """,
+                    self._memory_to_row(memory),
+                )
+                conn.commit()
+            finally:
+                conn.close()
+        return memory
+
+    def get(self, memory_id: str) -> Memory | None:
+        with self._lock:
+            conn = self._connect()
+            try:
+                row = conn.execute(
+                    "SELECT * FROM memories WHERE id = ?", (memory_id,)
+                ).fetchone()
+                return self._row_to_memory(row) if row else None
+            finally:
+                conn.close()
+
+    def update(self, memory: Memory) -> Memory:
+        with self._lock:
+            conn = self._connect()
+            try:
+                conn.execute(
+                    """
+                    UPDATE memories SET
+                        text=?, timestamp=?, tags=?, importance=?,
+                        access_count=?, metadata=?
+                    WHERE id=?
+                    """,
+                    (
+                        memory.text,
+                        memory.timestamp.isoformat(),
+                        json.dumps(memory.tags),
+                        memory.importance,
+                        memory.access_count,
+                        json.dumps(memory.metadata),
+                        memory.id,
+                    ),
+                )
+                conn.commit()
+            finally:
+                conn.close()
+        return memory
+
+    def delete(self, memory_id: str) -> bool:
+        with self._lock:
+            conn = self._connect()
+            try:
+                cur = conn.execute("DELETE FROM memories WHERE id = ?", (memory_id,))
+                conn.commit()
+                return cur.rowcount > 0
+            finally:
+                conn.close()
+
+    def list_all(self) -> list[Memory]:
+        with self._lock:
+            conn = self._connect()
+            try:
+                rows = conn.execute(
+                    "SELECT * FROM memories ORDER BY timestamp DESC"
+                ).fetchall()
+                return [self._row_to_memory(r) for r in rows]
+            finally:
+                conn.close()
+
+    def count(self) -> int:
+        with self._lock:
+            conn = self._connect()
+            try:
+                row = conn.execute("SELECT COUNT(*) AS c FROM memories").fetchone()
+                return int(row["c"]) if row else 0
+            finally:
+                conn.close()
+
+    def export_records(self) -> list[dict[str, Any]]:
+        return [m.to_dict() for m in self.list_all()]
+
+    def import_records(self, records: list[dict[str, Any]]) -> int:
+        count = 0
+        for record in records:
+            memory = Memory.from_dict(record)
+            if self.get(memory.id):
+                self.update(memory)
+            else:
+                self.add(memory)
+            count += 1
+        return count
+
+    def db_file_size_bytes(self) -> int:
+        if self._db_path.exists():
+            return self._db_path.stat().st_size
+        return 0
+
+    def tag_counts(self) -> dict[str, int]:
+        counts: dict[str, int] = {}
+        for memory in self.list_all():
+            for tag in memory.tags:
+                counts[tag] = counts.get(tag, 0) + 1
+        return counts

memorybrain-1.0.0/memorybrain.egg-info/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: memorybrain
+Version: 1.0.0
+Summary: Long-term memory library for AI assistants and agents
+Home-page: https://github.com/memorybrain/memorybrain
+Author: MemoryBrain Contributors
+Author-email: memorybrain@example.com
+License: MIT
+Project-URL: Source, https://github.com/memorybrain/memorybrain
+Project-URL: Tracker, https://github.com/memorybrain/memorybrain/issues
+Keywords: ai memory agents llm chatbot sqlite
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/plain
+License-File: LICENSE.txt
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+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
+
+
+MIT License
+
+Copyright (c) 2026 MemoryBrain Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memorybrain-1.0.0/memorybrain.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+Changelog.txt
+LICENSE.txt
+MANIFEST.in
+README.txt
+requirements.txt
+setup.py
+memorybrain/__init__.py
+memorybrain/brain.py
+memorybrain/ranking.py
+memorybrain/search.py
+memorybrain/storage.py
+memorybrain.egg-info/PKG-INFO
+memorybrain.egg-info/SOURCES.txt
+memorybrain.egg-info/dependency_links.txt
+memorybrain.egg-info/top_level.txt
+tests/test_memorybrain.py

memorybrain-1.0.0/memorybrain.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

memorybrain-1.0.0/memorybrain.egg-info/top_level.txt

@@ -0,0 +1 @@
+memorybrain

memorybrain-1.0.0/requirements.txt

@@ -0,0 +1,8 @@
+# memorybrain runtime requirements
+# Python 3.10+ standard library only (sqlite3, json, threading, etc.)
+# No third-party packages required for installation.
+
+# Optional development / publishing dependencies:
+# wheel
+# twine
+# build

memorybrain-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

memorybrain-1.0.0/setup.py

@@ -0,0 +1,44 @@
+"""Setup script for memorybrain package."""
+
+from pathlib import Path
+
+from setuptools import find_packages, setup
+
+HERE = Path(__file__).parent.resolve()
+README = (HERE / "README.txt").read_text(encoding="utf-8")
+LICENSE = (HERE / "LICENSE.txt").read_text(encoding="utf-8")
+
+setup(
+    name="memorybrain",
+    version="1.0.0",
+    description="Long-term memory library for AI assistants and agents",
+    long_description=README + "\n\n" + LICENSE,
+    long_description_content_type="text/plain",
+    author="MemoryBrain Contributors",
+    author_email="memorybrain@example.com",
+    url="https://github.com/memorybrain/memorybrain",
+    license="MIT",
+    packages=find_packages(exclude=["tests", "tests.*"]),
+    python_requires=">=3.10",
+    install_requires=[],
+    include_package_data=True,
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+        "Typing :: Typed",
+    ],
+    keywords="ai memory agents llm chatbot sqlite",
+    project_urls={
+        "Source": "https://github.com/memorybrain/memorybrain",
+        "Tracker": "https://github.com/memorybrain/memorybrain/issues",
+    },
+)

memorybrain-1.0.0/tests/test_memorybrain.py

@@ -0,0 +1,57 @@
+"""Tests for memorybrain package."""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+from memorybrain import MemoryBrain
+
+
+def test_remember_recall_search() -> None:
+    with tempfile.TemporaryDirectory() as tmp:
+        db = Path(tmp) / "test.db"
+        brain = MemoryBrain(db_path=db)
+        m = brain.remember(
+            "User likes Flutter development",
+            tags=["flutter", "programming"],
+            importance=10,
+        )
+        assert m.id
+        recall = brain.recall("What framework does the user like?")
+        assert len(recall) >= 1
+        assert "Flutter" in recall[0].text
+        search = brain.search("Flutter")
+        assert len(search) >= 1
+
+
+def test_forget_export_import_stats() -> None:
+    with tempfile.TemporaryDirectory() as tmp:
+        db = Path(tmp) / "test.db"
+        brain = MemoryBrain(db_path=db)
+        m = brain.remember("Temporary memory", tags=["temp"], importance=3)
+        export_path = Path(tmp) / "memories.json"
+        assert brain.export(export_path) == 1
+        assert brain.forget(m.id) is True
+        assert brain.get(m.id) is None
+        count = brain.import_file(export_path)
+        assert count == 1
+        assert brain.get(m.id) is not None
+        stats = brain.stats()
+        assert stats["total_memories"] == 1
+        assert "most_common_tags" in stats
+        assert "database_size_bytes" in stats
+        assert stats["database_size_bytes"] > 0
+
+
+def test_import_export_roundtrip() -> None:
+    with tempfile.TemporaryDirectory() as tmp:
+        db = Path(tmp) / "test.db"
+        brain = MemoryBrain(db_path=db)
+        brain.remember("Note one", tags=["a"])
+        brain.remember("Note two", tags=["b"])
+        path = Path(tmp) / "out.json"
+        brain.export(path)
+        data = json.loads(path.read_text(encoding="utf-8"))
+        assert len(data) == 2