memlife 0.1.0b0__tar.gz

memlife-0.1.0b0/LICENSE

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

memlife-0.1.0b0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: memlife
+Version: 0.1.0b0
+Summary: Memory that degrades gracefully — four-tier lifecycle memory for AI agents
+Author-email: EzyRider <ezyrider70@gmail.com>
+License: MIT
+Keywords: memory,ai,agent,lifecycle,decay,reflection,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: ollama
+Requires-Dist: aiohttp; extra == "ollama"
+Provides-Extra: openai
+Requires-Dist: openai; extra == "openai"
+Provides-Extra: sentence-transformers
+Requires-Dist: sentence-transformers; extra == "sentence-transformers"
+Provides-Extra: mcp
+Requires-Dist: mcp; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# memlife
+
+Memory that degrades gracefully. Not another pile that grows forever.
+
+## What
+
+memlife is a four-tier lifecycle memory system for AI agents:
+
+- **Episodes** — raw events (what happened)
+- **Facts** — durable truths (what I know)
+- **Journal** — reflected beliefs (what I believe)
+- **Decay/Prune** — confidence fades, stale entries retire, GC cleans up
+
+Every memory has a lifecycle. Facts decay through confidence erosion. Journal entries retire when they fall below the floor. Superseded data is pruned after a retention period. Nothing accumulates forever.
+
+## Why
+
+Every other memory system accumulates. Facts never expire. Confidence never decays. Stale conventions become unquestioned truths. Recall quality degrades over time.
+
+memlife solves this. Memory should be like human memory — it fades, it gets revised, it gets pruned. Not a database that grows until it breaks.
+
+## Quickstart
+
+```bash
+pip install memlife
+```
+
+```python
+import asyncio
+from memlife import MemoryStore, MemoryConfig, DummyEmbedder
+
+async def main():
+    store = MemoryStore(
+        config=MemoryConfig(db_path="./mem.db"),
+        embedder=DummyEmbedder(),  # zero external dependencies
+    )
+
+    # Store an episode (something happened)
+    store.remember(task="User asked about deployment", outcome="success")
+
+    # Store a fact (durable truth)
+    await store.store_fact("User deploys via GitHub Actions", confidence=0.8)
+
+    # Retrieve relevant memories (unified scoring across all layers)
+    context = await store.retrieve("deployment")
+
+    print(context)
+    store.close()
+
+asyncio.run(main())
+```
+
+No Ollama, no OpenAI, no API key. The DummyEmbedder uses hash-based vectors. The full lifecycle — store, retrieve, decay, GC — works without any LLM.
+
+## The Lifecycle
+
+```
+┌───────────┐     reflection      ┌───────────┐
+│  EPISODE  │ ──────────────────▶ │  JOURNAL  │
+│  (event)  │   LLM synthesises    │ (belief)  │
+└─────┬─────┘   observations &    └─────┬─────┘
+      │         hypotheses              │
+      │                                  │
+      │ store_fact()                    │ confidence decay
+      ▼                                  │ (30d halflife)
+┌───────────┐    recall bumps     ┌─────▼─────┐
+│   FACT    │ ◀────────────────   │  RETIRE   │
+│  (truth)  │   confidence +0.05  │ (floor)   │
+└─────┬─────┘                     └─────┬─────┘
+      │                                 │
+      │ revise / supersede              │ GC prunes
+      ▼                                 ▼
+┌───────────┐                      ┌───────────┐
+│ SUPERSEDED│   90 days retention  │  PRUNED   │
+│ (replaced)│ ───────────────────▶ │ (deleted) │
+└───────────┘                      └───────────┘
+
+UNIFIED SCORE = relevance × confidence × recency
+Applied across ALL layers before every response.
+```
+
+## No-LLM Mode
+
+The store, retrieval, decay, GC, and embedding versioning all work without any LLM. Only the reflection loop needs a model. If you just want durable, decaying memory:
+
+```python
+store = MemoryStore(config=MemoryConfig(db_path="./mem.db"))
+store.remember(task="something happened", outcome="success")
+context = await store.retrieve("something")
+```
+
+## With Reflection
+
+```python
+from memlife import MemoryStore, MemoryConfig, Reflector, DummyEmbedder, DummyChat
+
+store = MemoryStore(
+    config=MemoryConfig(db_path="./mem.db"),
+    embedder=DummyEmbedder(),
+)
+reflector = Reflector(
+    memory=store,
+    model_chat=DummyChat(),
+    critic=False,
+)
+result = await reflector.reflect()
+```
+
+For real LLMs, implement the `Embedder` and `ChatCallable` protocols, or use an adapter (Phase 2).
+
+## Features
+
+- Four-tier lifecycle: Episode → Fact → Journal → Decay/Prune
+- Unified scoring: relevance × confidence × recency across all layers
+- Confidence ceiling (0.99) — facts are never immutable
+- Confidence decay with 30-day halflife — journal entries fade
+- GC with configurable retention (90 days for superseded facts, etc.)
+- Embedding versioning — detect stale vectors when the model changes
+- Episode tool index — search "have I used this tool before?"
+- Incremental contradiction detection — O(new × n), not O(n²)
+- JSONL import/export for backup and migration
+- SQLite-backed, single file, zero external services
+- Works with zero dependencies (DummyEmbedder + DummyChat)
+
+## Status
+
+**v0.1.0-beta.** The API may change before v1.0.
+
+## License
+
+MIT

memlife-0.1.0b0/README.md

@@ -0,0 +1,131 @@
+# memlife
+
+Memory that degrades gracefully. Not another pile that grows forever.
+
+## What
+
+memlife is a four-tier lifecycle memory system for AI agents:
+
+- **Episodes** — raw events (what happened)
+- **Facts** — durable truths (what I know)
+- **Journal** — reflected beliefs (what I believe)
+- **Decay/Prune** — confidence fades, stale entries retire, GC cleans up
+
+Every memory has a lifecycle. Facts decay through confidence erosion. Journal entries retire when they fall below the floor. Superseded data is pruned after a retention period. Nothing accumulates forever.
+
+## Why
+
+Every other memory system accumulates. Facts never expire. Confidence never decays. Stale conventions become unquestioned truths. Recall quality degrades over time.
+
+memlife solves this. Memory should be like human memory — it fades, it gets revised, it gets pruned. Not a database that grows until it breaks.
+
+## Quickstart
+
+```bash
+pip install memlife
+```
+
+```python
+import asyncio
+from memlife import MemoryStore, MemoryConfig, DummyEmbedder
+
+async def main():
+    store = MemoryStore(
+        config=MemoryConfig(db_path="./mem.db"),
+        embedder=DummyEmbedder(),  # zero external dependencies
+    )
+
+    # Store an episode (something happened)
+    store.remember(task="User asked about deployment", outcome="success")
+
+    # Store a fact (durable truth)
+    await store.store_fact("User deploys via GitHub Actions", confidence=0.8)
+
+    # Retrieve relevant memories (unified scoring across all layers)
+    context = await store.retrieve("deployment")
+
+    print(context)
+    store.close()
+
+asyncio.run(main())
+```
+
+No Ollama, no OpenAI, no API key. The DummyEmbedder uses hash-based vectors. The full lifecycle — store, retrieve, decay, GC — works without any LLM.
+
+## The Lifecycle
+
+```
+┌───────────┐     reflection      ┌───────────┐
+│  EPISODE  │ ──────────────────▶ │  JOURNAL  │
+│  (event)  │   LLM synthesises    │ (belief)  │
+└─────┬─────┘   observations &    └─────┬─────┘
+      │         hypotheses              │
+      │                                  │
+      │ store_fact()                    │ confidence decay
+      ▼                                  │ (30d halflife)
+┌───────────┐    recall bumps     ┌─────▼─────┐
+│   FACT    │ ◀────────────────   │  RETIRE   │
+│  (truth)  │   confidence +0.05  │ (floor)   │
+└─────┬─────┘                     └─────┬─────┘
+      │                                 │
+      │ revise / supersede              │ GC prunes
+      ▼                                 ▼
+┌───────────┐                      ┌───────────┐
+│ SUPERSEDED│   90 days retention  │  PRUNED   │
+│ (replaced)│ ───────────────────▶ │ (deleted) │
+└───────────┘                      └───────────┘
+
+UNIFIED SCORE = relevance × confidence × recency
+Applied across ALL layers before every response.
+```
+
+## No-LLM Mode
+
+The store, retrieval, decay, GC, and embedding versioning all work without any LLM. Only the reflection loop needs a model. If you just want durable, decaying memory:
+
+```python
+store = MemoryStore(config=MemoryConfig(db_path="./mem.db"))
+store.remember(task="something happened", outcome="success")
+context = await store.retrieve("something")
+```
+
+## With Reflection
+
+```python
+from memlife import MemoryStore, MemoryConfig, Reflector, DummyEmbedder, DummyChat
+
+store = MemoryStore(
+    config=MemoryConfig(db_path="./mem.db"),
+    embedder=DummyEmbedder(),
+)
+reflector = Reflector(
+    memory=store,
+    model_chat=DummyChat(),
+    critic=False,
+)
+result = await reflector.reflect()
+```
+
+For real LLMs, implement the `Embedder` and `ChatCallable` protocols, or use an adapter (Phase 2).
+
+## Features
+
+- Four-tier lifecycle: Episode → Fact → Journal → Decay/Prune
+- Unified scoring: relevance × confidence × recency across all layers
+- Confidence ceiling (0.99) — facts are never immutable
+- Confidence decay with 30-day halflife — journal entries fade
+- GC with configurable retention (90 days for superseded facts, etc.)
+- Embedding versioning — detect stale vectors when the model changes
+- Episode tool index — search "have I used this tool before?"
+- Incremental contradiction detection — O(new × n), not O(n²)
+- JSONL import/export for backup and migration
+- SQLite-backed, single file, zero external services
+- Works with zero dependencies (DummyEmbedder + DummyChat)
+
+## Status
+
+**v0.1.0-beta.** The API may change before v1.0.
+
+## License
+
+MIT

memlife-0.1.0b0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "memlife"
+version = "0.1.0b0"
+description = "Memory that degrades gracefully — four-tier lifecycle memory for AI agents"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "EzyRider", email = "ezyrider70@gmail.com"}]
+keywords = ["memory", "ai", "agent", "lifecycle", "decay", "reflection", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.optional-dependencies]
+ollama = ["aiohttp"]
+openai = ["openai"]
+sentence-transformers = ["sentence-transformers"]
+mcp = ["mcp"]
+dev = ["pytest", "pytest-asyncio", "ruff"]
+
+# [project.scripts]
+# memlife-mcp-server = "memlife.mcp_server:main"  # Phase 3: MCP server not yet implemented
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

memlife-0.1.0b0/setup.cfg

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

memlife-0.1.0b0/src/memlife/__init__.py

@@ -0,0 +1,51 @@
+"""memlife — memory that degrades gracefully.
+
+Four-tier lifecycle memory for AI agents:
+  Episode → Fact → Journal → Decay/Prune
+
+Unified scoring: relevance × confidence × recency.
+No-LLM mode: store, retrieve, decay, and GC work without any model.
+Only reflection needs an LLM.
+
+Quickstart:
+    from memlife import MemoryStore, MemoryConfig
+    store = MemoryStore(MemoryConfig(db_path="./mem.db"))
+    store.remember(task="hello", outcome="success")
+    context = await store.retrieve("hello", config=MemoryConfig())
+"""
+
+from memlife.config import MemoryConfig
+from memlife.models import Episode, Fact, JournalEntry
+from memlife.protocols import ChatCallable, Embedder
+from memlife.embedders import DummyEmbedder
+from memlife.llm import DummyChat
+from memlife.reflection import Reflector, ReflectionResult
+from memlife.store import MemoryStore
+from memlife.vectors import cosine, recency_weight
+
+__version__ = "0.1.0b0"
+
+__all__ = [
+    "MemoryStore",
+    "MemoryConfig",
+    "Reflector",
+    "ReflectionResult",
+    "Episode",
+    "Fact",
+    "JournalEntry",
+    "Embedder",
+    "ChatCallable",
+    "DummyEmbedder",
+    "DummyChat",
+    "cosine",
+    "recency_weight",
+    "retrieve",
+    "run_gc",
+    "export_jsonl",
+    "import_jsonl",
+]
+
+# Convenience imports
+from memlife.retrieval import retrieve
+from memlife.gc import run_gc
+from memlife.io import export_jsonl, import_jsonl

memlife-0.1.0b0/src/memlife/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Adapters package — reference implementations for common embedders and LLMs.
+
+Each adapter implements the Embedder or ChatCallable protocol from memlife.protocols.
+Adapters are optional — the core library works with DummyEmbedder and DummyChat.
+"""

memlife-0.1.0b0/src/memlife/config.py

@@ -0,0 +1,98 @@
+"""Memory configuration — memory fields only, no agent config."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class MemoryConfig:
+    """Configuration for the memory system.
+
+    All fields have sensible defaults. The store works with zero
+    configuration — just ``MemoryConfig()``.
+
+    Env vars (optional, override defaults):
+      MEMLIFE_DB_PATH, MEMLIFE_EMBEDDING_MODEL, etc.
+    """
+
+    # Database
+    db_path: str = "./memlife.db"
+
+    # Embedding model name (stored with each vector for versioning)
+    embedding_model: str = ""
+
+    # Retrieval — how much context to inject before responding
+    recall_episodes: int = 5
+    recall_facts: int = 5
+    recall_journal: int = 3
+    working_window: int = 20
+    max_context_chars: int = 4000
+    recency_halflife_days: float = 14.0
+
+    # Strict recall cut-off + density dedup
+    recall_min_score: float = 0.0
+    recall_score_cutoff_ratio: float = 0.0
+    recall_dedup_threshold: float = 0.75
+    recall_dedup_method: str = "jaccard"
+
+    # Fact memory — cosine bands for merge and conflict detection
+    fact_merge_threshold: float = 0.90
+    fact_conflict_threshold: float = 0.75
+
+    # Reflection quality
+    reflect_critic: bool = True
+    critic_model: str = ""  # empty = use primary model; set to a cheap model for the critic pass
+    significance_model: str = ""
+    journal_decay_halflife_days: float = 30.0
+    journal_decay_floor: float = 0.15
+
+    # Reflection timeouts
+    reflection_timeout: float = 120.0
+    reflection_total_timeout: float = 300.0
+
+    # GC retention (days)
+    gc_superseded_facts_days: int = 90
+    gc_superseded_journal_days: int = 90
+    gc_completed_runs_days: int = 60
+    gc_metrics_days: int = 30
+    gc_reflected_queue_days: int = 30
+
+    @classmethod
+    def from_env(cls) -> "MemoryConfig":
+        """Load from environment variables with MEMLIFE_ prefix."""
+        import os
+
+        def _bool(name: str, default: bool) -> bool:
+            val = os.getenv(name)
+            if val is None:
+                return default
+            return val.strip().lower() in ("1", "true", "yes", "on")
+
+        return cls(
+            db_path=os.getenv("MEMLIFE_DB_PATH", "./memlife.db"),
+            embedding_model=os.getenv("MEMLIFE_EMBEDDING_MODEL", ""),
+            recall_episodes=int(os.getenv("MEMLIFE_RECALL_EPISODES", "5")),
+            recall_facts=int(os.getenv("MEMLIFE_RECALL_FACTS", "5")),
+            recall_journal=int(os.getenv("MEMLIFE_RECALL_JOURNAL", "3")),
+            working_window=int(os.getenv("MEMLIFE_WORKING_WINDOW", "20")),
+            max_context_chars=int(os.getenv("MEMLIFE_MAX_CONTEXT_CHARS", "4000")),
+            recency_halflife_days=float(os.getenv("MEMLIFE_RECENCY_HALFLIFE_DAYS", "14")),
+            recall_min_score=float(os.getenv("MEMLIFE_RECALL_MIN_SCORE", "0")),
+            recall_score_cutoff_ratio=float(os.getenv("MEMLIFE_RECALL_SCORE_CUTOFF_RATIO", "0")),
+            recall_dedup_threshold=float(os.getenv("MEMLIFE_RECALL_DEDUP_THRESHOLD", "0.75")),
+            recall_dedup_method=os.getenv("MEMLIFE_RECALL_DEDUP_METHOD", "jaccard"),
+            fact_merge_threshold=float(os.getenv("MEMLIFE_FACT_MERGE_THRESHOLD", "0.90")),
+            fact_conflict_threshold=float(os.getenv("MEMLIFE_FACT_CONFLICT_THRESHOLD", "0.75")),
+            reflect_critic=_bool("MEMLIFE_REFLECT_CRITIC", True),
+            critic_model=os.getenv("MEMLIFE_CRITIC_MODEL", ""),
+            journal_decay_halflife_days=float(os.getenv("MEMLIFE_JOURNAL_HALFLIFE_DAYS", "30")),
+            journal_decay_floor=float(os.getenv("MEMLIFE_JOURNAL_DECAY_FLOOR", "0.15")),
+            reflection_timeout=float(os.getenv("MEMLIFE_REFLECTION_TIMEOUT", "120")),
+            reflection_total_timeout=float(os.getenv("MEMLIFE_REFLECTION_TOTAL_TIMEOUT", "300")),
+            gc_superseded_facts_days=int(os.getenv("MEMLIFE_GC_SUPERSEDED_FACTS_DAYS", "90")),
+            gc_superseded_journal_days=int(os.getenv("MEMLIFE_GC_SUPERSEDED_JOURNAL_DAYS", "90")),
+            gc_completed_runs_days=int(os.getenv("MEMLIFE_GC_COMPLETED_RUNS_DAYS", "60")),
+            gc_metrics_days=int(os.getenv("MEMLIFE_GC_METRICS_DAYS", "30")),
+            gc_reflected_queue_days=int(os.getenv("MEMLIFE_GC_REFLECTED_QUEUE_DAYS", "30")),
+        )

memlife-0.1.0b0/src/memlife/embedders.py

@@ -0,0 +1,26 @@
+"""DummyEmbedder — hash-based embeddings for testing and quickstart.
+
+Zero external dependencies, no API calls, deterministic.
+Produces 128-dimensional vectors from SHA-256 hashes.
+Good enough for keyword-like similarity, not for real semantic recall.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Sequence
+
+
+class DummyEmbedder:
+    """Hash-based embeddings. No external dependencies.
+
+    Implements the Embedder protocol: ``await embedder.embed(texts)``.
+    """
+
+    async def embed(self, texts: Sequence[str]) -> list[list[float]] | None:
+        return [self._hash_vector(t) for t in texts]
+
+    @staticmethod
+    def _hash_vector(text: str, dim: int = 128) -> list[float]:
+        h = hashlib.sha256(text.encode("utf-8")).digest()
+        return [((h[i % len(h)] / 255.0) - 0.5) * 2.0 for i in range(dim)]

memlife-0.1.0b0/src/memlife/gc.py

@@ -0,0 +1,28 @@
+"""Garbage collection for the memory store."""
+
+from __future__ import annotations
+
+from memlife.store import MemoryStore
+
+
+def run_gc(
+    store: MemoryStore,
+    *,
+    superseded_facts_days: int = 90,
+    superseded_journal_days: int = 90,
+    completed_runs_days: int = 60,
+    metrics_days: int = 30,
+    reflected_queue_days: int = 30,
+) -> dict:
+    """Run garbage collection on old/superseded data.
+
+    Delegates to MemoryStore.run_gc() — this wrapper is the public entry
+    point. Most callers should use ``store.run_gc()`` directly.
+    """
+    return store.run_gc(
+        superseded_facts_days=superseded_facts_days,
+        superseded_journal_days=superseded_journal_days,
+        completed_runs_days=completed_runs_days,
+        metrics_days=metrics_days,
+        reflected_queue_days=reflected_queue_days,
+    )