bubble-memory 0.1.0__tar.gz

bubble_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AutismAccelerator
+
+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.

bubble_memory-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: bubble-memory
+Version: 0.1.0
+Summary: Event Sourcing based belief formation system for long-term AI agent memory
+Author-email: AutismAccelerator <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/AutismAccelerator/bubble
+Project-URL: Repository, https://github.com/AutismAccelerator/bubble
+Project-URL: Issues, https://github.com/AutismAccelerator/bubble/issues
+Keywords: ai,memory,agent,graph,llm,vector-store
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.86.0
+Requires-Dist: falkordb>=1.6.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: scikit-learn>=1.8.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Bubble
+**Event Sourcing based belief formation system for long-term AI agent memory**
+**[paper](https://doi.org/10.5281/zenodo.19438945)**   **[Discord](https://discord.com/users/1319641673990672477)**
+
+---
+
+## How it works
+```
+[ raw input ]
+                               │
+                         ┌─────▼─────┐
+                         │ decompose │
+                         └─────┬─────┘
+                               │
+              ┌────────────────┴────────────────┐
+          ι ≥ θ                             ι < θ
+              │                                 │
+        vivid signal                       weak signal
+              │                                 │
+         ┌────▼────┐                     ┌──────▼──────┐
+         │ archive │                     │    pool     │
+         └────┬────┘                     │  · · · · ·  │
+              │                          │ ·  · ·  · · │
+              │                          │  · · · ·  · │
+              │                          └──────┬──────┘
+              │                                 │
+              │                          enough gathered?
+              │                                 │
+              │                    no ──────────┘
+              │                                 │ yes
+              │                          ┌──────▼──────┐
+              │                          │   cluster   │
+              │                          │   + score   │
+              │                          └──────┬──────┘
+              │                                 │
+              └──────────────┬──────────────────┘
+                             │
+                       ┌─────▼─────┐
+                       │  episode  │  immutable
+                       └─────┬─────┘
+                             │
+                     same topic chain?(NLI)
+                      yes │       │ no
+                          │       │
+               ┌──────────▼─┐   ┌▼────────────┐
+   joins chain │ ... ──► e  │   │     e       │  new chain
+               └──────────┬─┘   └─────┬───────┘
+                          │           │
+                    ┌─────▼───────────▼─────┐
+                    │       snapshot        │
+                    │  centroid  │  summary │ 
+                    │  (eager)   │  (lazy)  │
+                    └───────────┬───────────┘
+                                │
+                           [ retrieve ]
+                                │
+               ┌────────────────┴─────────────────┐
+           default                            verbose
+               │                                  │
+         snapshot summary             with episode chain + labels
+```
+## Setup
+### 1.run [Falkordb](https://github.com/falkordb/falkordb) 
+```bash
+docker run -e REDIS_ARGS="--appendonly yes --appendfsync everysec" -v <PATH>:/var/lib/falkordb/data -p 3000:3000 -p 6379:6379 -d --name falkordb falkordb/falkordb
+```
+### 2.embedding model(Matryoshka)
+**note: command below is cpu version**
+```bash
+docker run --name tei-embedding -d -p 8997:80 -v <PATH>:/data --pull always ghcr.io/huggingface/text-embeddings-inference:cpu-latest --model-id nomic-ai/nomic-embed-text-v1.5
+
+```
+Or embedding cloud api
+
+### 3.NLI model(Optional, but recommended, saves some LLM calls)
+**note: command below is cpu version**
+```bash
+docker run --name tei-nli -d -p 8999:80 -v <PATH>:/data --pull always ghcr.io/huggingface/text-embeddings-inference:cpu-latest --model-id cross-encoder/nli-deberta-v3-small
+```
+
+
+### Necessary configuration in your .env file
+```python
+ANTHROPIC_API_KEY=
+FALKORDB_HOST=localhost
+FALKORDB_PORT=6379
+BUBBLE_EMBED_DIM=768
+BUBBLE_EMBED_ENDPOINT=http://localhost:8997/v1/embeddings
+
+#If you have NLI setup
+BUBBLE_ENABLE_NLI=true
+BUBBLE_NLI_ENDPOINT=http://localhost:8999/predict
+```
+
+## How to use (extremely easy and clean)
+### ingest
+```python
+import bubble
+bubble.process(user_id, content, prior)
+```
+prior: the context of the content, for example prior messages
+### retrieve
+```python
+import bubble
+memory_user = await bubble.retrieve(user_id, query)
+```
+
+## Replayability 
+Memory episodes are archived in `<project root>/data/archive` as jsonl\
+You can reconstruct your whole memory graph by a single command ! WITHOUT A SINGLE LLM CALL !
+```python
+python -m bubble.main replay <user_id>
+```
+
+## Tuning/Customization
+See [.env.example](.env.example) for ALL tunable arguments.
+
+## Limitations
+Bubble is currently an experimental project for personal use.\
+Current `promotion formula`, env vars might not be the best.
+`prompts` might have much room to improve. Patch **bubble.decomposer._SYSTEM** if it doesn't fit your use case.\
+\
+Leave a star if you like this work. Contributions are welcome.

bubble_memory-0.1.0/README.md

@@ -0,0 +1,123 @@
+# Bubble
+**Event Sourcing based belief formation system for long-term AI agent memory**
+**[paper](https://doi.org/10.5281/zenodo.19438945)**   **[Discord](https://discord.com/users/1319641673990672477)**
+
+---
+
+## How it works
+```
+[ raw input ]
+                               │
+                         ┌─────▼─────┐
+                         │ decompose │
+                         └─────┬─────┘
+                               │
+              ┌────────────────┴────────────────┐
+          ι ≥ θ                             ι < θ
+              │                                 │
+        vivid signal                       weak signal
+              │                                 │
+         ┌────▼────┐                     ┌──────▼──────┐
+         │ archive │                     │    pool     │
+         └────┬────┘                     │  · · · · ·  │
+              │                          │ ·  · ·  · · │
+              │                          │  · · · ·  · │
+              │                          └──────┬──────┘
+              │                                 │
+              │                          enough gathered?
+              │                                 │
+              │                    no ──────────┘
+              │                                 │ yes
+              │                          ┌──────▼──────┐
+              │                          │   cluster   │
+              │                          │   + score   │
+              │                          └──────┬──────┘
+              │                                 │
+              └──────────────┬──────────────────┘
+                             │
+                       ┌─────▼─────┐
+                       │  episode  │  immutable
+                       └─────┬─────┘
+                             │
+                     same topic chain?(NLI)
+                      yes │       │ no
+                          │       │
+               ┌──────────▼─┐   ┌▼────────────┐
+   joins chain │ ... ──► e  │   │     e       │  new chain
+               └──────────┬─┘   └─────┬───────┘
+                          │           │
+                    ┌─────▼───────────▼─────┐
+                    │       snapshot        │
+                    │  centroid  │  summary │ 
+                    │  (eager)   │  (lazy)  │
+                    └───────────┬───────────┘
+                                │
+                           [ retrieve ]
+                                │
+               ┌────────────────┴─────────────────┐
+           default                            verbose
+               │                                  │
+         snapshot summary             with episode chain + labels
+```
+## Setup
+### 1.run [Falkordb](https://github.com/falkordb/falkordb) 
+```bash
+docker run -e REDIS_ARGS="--appendonly yes --appendfsync everysec" -v <PATH>:/var/lib/falkordb/data -p 3000:3000 -p 6379:6379 -d --name falkordb falkordb/falkordb
+```
+### 2.embedding model(Matryoshka)
+**note: command below is cpu version**
+```bash
+docker run --name tei-embedding -d -p 8997:80 -v <PATH>:/data --pull always ghcr.io/huggingface/text-embeddings-inference:cpu-latest --model-id nomic-ai/nomic-embed-text-v1.5
+
+```
+Or embedding cloud api
+
+### 3.NLI model(Optional, but recommended, saves some LLM calls)
+**note: command below is cpu version**
+```bash
+docker run --name tei-nli -d -p 8999:80 -v <PATH>:/data --pull always ghcr.io/huggingface/text-embeddings-inference:cpu-latest --model-id cross-encoder/nli-deberta-v3-small
+```
+
+
+### Necessary configuration in your .env file
+```python
+ANTHROPIC_API_KEY=
+FALKORDB_HOST=localhost
+FALKORDB_PORT=6379
+BUBBLE_EMBED_DIM=768
+BUBBLE_EMBED_ENDPOINT=http://localhost:8997/v1/embeddings
+
+#If you have NLI setup
+BUBBLE_ENABLE_NLI=true
+BUBBLE_NLI_ENDPOINT=http://localhost:8999/predict
+```
+
+## How to use (extremely easy and clean)
+### ingest
+```python
+import bubble
+bubble.process(user_id, content, prior)
+```
+prior: the context of the content, for example prior messages
+### retrieve
+```python
+import bubble
+memory_user = await bubble.retrieve(user_id, query)
+```
+
+## Replayability 
+Memory episodes are archived in `<project root>/data/archive` as jsonl\
+You can reconstruct your whole memory graph by a single command ! WITHOUT A SINGLE LLM CALL !
+```python
+python -m bubble.main replay <user_id>
+```
+
+## Tuning/Customization
+See [.env.example](.env.example) for ALL tunable arguments.
+
+## Limitations
+Bubble is currently an experimental project for personal use.\
+Current `promotion formula`, env vars might not be the best.
+`prompts` might have much room to improve. Patch **bubble.decomposer._SYSTEM** if it doesn't fit your use case.\
+\
+Leave a star if you like this work. Contributions are welcome.

bubble_memory-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bubble-memory"
+version = "0.1.0"
+description = "Event Sourcing based belief formation system for long-term AI agent memory"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "AutismAccelerator", email = "your.email@example.com"}
+]
+keywords = ["ai", "memory", "agent", "graph", "llm", "vector-store"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "anthropic>=0.86.0",
+    "falkordb>=1.6.0",
+    "httpx>=0.28.0",
+    "numpy>=2.4.4",
+    "python-dotenv>=1.2.2",
+    "scikit-learn>=1.8.0"
+]
+
+[project.optional-dependencies]
+dev = ["build", "twine", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/AutismAccelerator/bubble"
+Repository = "https://github.com/AutismAccelerator/bubble"
+Issues = "https://github.com/AutismAccelerator/bubble/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 230

bubble_memory-0.1.0/setup.cfg

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

bubble_memory-0.1.0/src/bubble/__init__.py

@@ -0,0 +1,101 @@
+"""
+bubble — Hierarchical Memory Consolidation System
+
+Typical agent usage
+-------------------
+    import bubble
+
+    # Once, when a user session starts:
+    await bubble.init_graph(user_id)
+
+    # On every user message — retrieve and store in one call (preferred):
+    result = await bubble.observe(user_id, message, prior=agent_reply)
+    context = result["retrieved"]  # SnapshotNode results relevant to this message
+    stored  = result["stored"]     # ingested node descriptors
+
+    # Or separately:
+    await bubble.process(user_id, message, prior=agent_reply)
+    context = await bubble.retrieve(user_id, query)
+
+    # Periodically (runs HDBSCAN + promotion):
+    await bubble.consolidate(user_id)
+
+    # retrieved is a list of dicts:
+    #   {id, summary, members: [{id, summary, confidence_label}],
+    #    context: [{rel, id, summary, confidence_label}]}
+"""
+
+import asyncio
+
+from .db import get_graph, init_graph
+from .embed import embed as _embed
+from .decomposer import decompose as _decompose
+from .ingest import _route_segments, ingest, replay
+from .promote import promote
+from .retrieve import _retrieve_from_vecs, retrieve
+
+
+async def observe(user_id: str, message: str, prior: str | None = None, top_k: int = 3, verbose: bool = False) -> dict:
+    """
+    Decompose once, retrieve relevant memories, then store — all in a single call.
+
+    Shares the decompose+embed step between retrieval and ingestion.
+    Retrieval runs before storage so newly ingested segments don't appear in results.
+
+    Returns:
+      {
+        "retrieved": [...],  # same format as retrieve()
+        "stored":    [...],  # same format as process()
+      }
+    """
+    segments = await _decompose(message, prior)
+    embeddings = list(await asyncio.gather(*[_embed(s["text"]) for s in segments]))
+
+    g = get_graph(user_id)
+    stored = await _route_segments(user_id, segments, embeddings, prior)
+    retrieved = await _retrieve_from_vecs(g, message, embeddings, top_k, verbose)
+    return {"retrieved": retrieved, "stored": stored}
+
+
+async def process(user_id: str, message: str, prior: str | None = None) -> list[dict]:
+    """
+    Ingest a message into the user's memory graph.
+
+    Routes each segment to:
+      - Episodic Episode (intensity >= 0.6): JSONL + Layer 1 node immediately
+      - Layer 0 active pool (everything else): waits for consolidate()
+
+    prior: optional conversational context the user is responding to.
+    Returns the list of created node descriptors.
+    """
+    nodes = await ingest(user_id, message, prior)
+    await promote(user_id)
+    return nodes
+
+
+async def consolidate(user_id: str) -> dict:
+    """
+    Run the full consolidation pipeline on a user's graph:
+      1. HDBSCAN on the Layer 0 active pool
+      2. Promote clusters crossing the t_promo_score threshold to Episodes
+         (includes JSONL archival, SegmentNode deletion, L2 assignment)
+
+    Returns:
+      {"promoted": [...]}  # newly created Episode descriptors
+
+    Call periodically rather than on every message.
+    """
+    promoted = await promote(user_id)
+    return {"promoted": promoted}
+
+
+__all__ = [
+    "init_graph",
+    "observe",
+    "process",
+    "consolidate",
+    "retrieve",
+    "ingest",
+    "promote",
+    "replay",
+]

bubble_memory-0.1.0/src/bubble/_shared.py

@@ -0,0 +1,49 @@
+import os
+from datetime import datetime, timezone
+
+import numpy as np
+from anthropic import AsyncAnthropic
+from dotenv import load_dotenv
+
+load_dotenv()
+
+MODEL = os.getenv("BUBBLE_MODEL", "claude-sonnet-4-6")
+_client = AsyncAnthropic()
+
+_SUMMARIZE_SYSTEM = """\
+You distill one or more user statements into a single memory record.
+
+Rules:
+- Capture the belief, preference, event, or tendency the statements express.
+- When multiple statements are given, identify the common pattern they share.
+- Write exactly one sentence with no grammatical subject.
+- Start with a verb or descriptor that names the belief, event, or pattern.
+- Do not explain, qualify, or ask for clarification.\
+"""
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _normalize(vec: np.ndarray) -> list[float]:
+    """L2-normalize a numpy vector and return as a Python list."""
+    norm = np.linalg.norm(vec)
+    return (vec / norm if norm > 0 else vec).tolist()
+
+
+def _centroid(nodes: list[dict]) -> list[float]:
+    """Mean of source embeddings, L2-normalized."""
+    matrix = np.array([n["embedding"] for n in nodes], dtype=np.float32)
+    return _normalize(matrix.mean(axis=0))
+
+
+async def _summarize(nodes: list[dict]) -> str:
+    texts = "\n".join(f"- {n['raw_text']}" for n in nodes)
+    response = await _client.messages.create(
+        model=MODEL,
+        max_tokens=128,
+        system=_SUMMARIZE_SYSTEM,
+        messages=[{"role": "user", "content": texts}],
+    )
+    return response.content[0].text.strip()

bubble_memory-0.1.0/src/bubble/archive.py

@@ -0,0 +1,48 @@
+import json
+import os
+from pathlib import Path
+
+_ARCHIVE_DIR = os.getenv("BUBBLE_ARCHIVE_DIR", "./data/archive")
+_MKDIR_DONE = False
+
+
+def _path(user_id: str) -> Path:
+    global _MKDIR_DONE
+    p = Path(_ARCHIVE_DIR)
+    if not _MKDIR_DONE:
+        p.mkdir(parents=True, exist_ok=True)
+        _MKDIR_DONE = True
+    return p / f"{user_id}.jsonl"
+
+
+def read_segments(user_id: str):
+    """Yield all archived segment records for a user."""
+    path = _path(user_id)
+    if not path.exists():
+        return
+    with path.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                yield json.loads(line)
+
+
+def write_segment(
+    user_id: str,
+    *,
+    text: str,
+    prior: str | None,
+    intensity: float,
+    valence: str,
+    timestamp: str,
+) -> None:
+    """Append one segment record to the user's JSONL archive."""
+    entry = {
+        "text":      text,
+        "prior":     prior,
+        "intensity": intensity,
+        "valence":   valence,
+        "timestamp": timestamp,
+    }
+    with _path(user_id).open("a", encoding="utf-8") as f:
+        f.write(json.dumps(entry) + "\n")