mimir-learn 0.1.0__py3-none-any.whl

mimir/__init__.py

@@ -0,0 +1,19 @@
+"""Mimir — experience-driven memory for autonomous agents."""
+
+from .core import Mimir
+from .embeddings import Embedder, NullEmbedder
+from .models import Experience, Outcome, Recommendation
+from .storage import SQLiteStorage, Storage
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Mimir",
+    "Experience",
+    "Outcome",
+    "Recommendation",
+    "Storage",
+    "SQLiteStorage",
+    "Embedder",
+    "NullEmbedder",
+]

mimir/core.py

@@ -0,0 +1,201 @@
+"""The Mimir public API.
+
+Everything users touch goes through this class. All writes funnel through a
+single chokepoint (`_write`) — that one method is the seam where validation,
+provenance tagging, and (future) a memory-firewall layer plug in without
+touching the rest of the system.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import threading
+from collections import defaultdict
+
+from .embeddings import Embedder, NullEmbedder, cosine_similarity
+from .models import Experience, Outcome, Recommendation
+from .storage import SQLiteStorage, Storage
+
+
+class Mimir:
+    def __init__(
+        self,
+        db_path: str = "mimir.db",
+        *,
+        storage: Storage | None = None,
+        embedder: Embedder | None = None,
+    ) -> None:
+        self._storage = storage or SQLiteStorage(db_path)
+        self._embedder = embedder or NullEmbedder()
+        self._lock = threading.Lock()
+
+    # -- writes -------------------------------------------------------------
+
+    def record(
+        self,
+        task: str,
+        action: str,
+        outcome: str | Outcome = Outcome.SUCCESS,
+        score: float | None = None,
+        context: dict | None = None,
+    ) -> Experience:
+        """Record an experience: a task, the action taken, and how it went."""
+        outcome = Outcome(outcome) if not isinstance(outcome, Outcome) else outcome
+        if score is None:
+            score = _default_score(outcome)
+        exp = Experience(
+            task=task,
+            action=action,
+            outcome=outcome,
+            score=score,
+            context=context or {},
+        )
+        return self._write(exp)
+
+    def record_failure(
+        self,
+        task: str,
+        action: str,
+        reason: str | None = None,
+        score: float = 0.0,
+        context: dict | None = None,
+    ) -> Experience:
+        """Record a failure. Stored like any experience but with outcome=failure,
+        so agents can recall what *didn't* work and stop repeating it."""
+        ctx = dict(context or {})
+        if reason:
+            ctx["failure_reason"] = reason
+        return self.record(task, action, outcome=Outcome.FAILURE, score=score, context=ctx)
+
+    def _write(self, exp: Experience) -> Experience:
+        """The single write chokepoint. Validation/provenance/firewall hooks go here."""
+        # Fail fast with a clear message rather than crashing deep in storage.
+        try:
+            json.dumps(exp.context)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"context must be JSON-serializable: {exc}") from exc
+        with self._lock:
+            if self._embedder.enabled and exp.embedding is None:
+                exp.embedding = self._embedder.embed(exp.text())
+            self._storage.add(exp)
+        return exp
+
+    # -- reads --------------------------------------------------------------
+
+    def recall(
+        self,
+        query: str,
+        k: int = 5,
+        outcome: str | Outcome | None = None,
+        context: dict | None = None,
+    ) -> list[Experience]:
+        """Return the most relevant past experiences for ``query``."""
+        outcome_val = outcome.value if isinstance(outcome, Outcome) else outcome
+        # Pull a wider candidate set so optional embedding rerank has room to work.
+        candidates = self._storage.search(
+            query, k=max(k * 4, k), outcome=outcome_val, context=context
+        )
+        if self._embedder.enabled:
+            candidates = self._rerank(query, candidates)
+        return [exp for exp, _ in candidates[:k]]
+
+    def get(self, experience_id: str) -> Experience | None:
+        """Fetch a single experience by id, or None if it doesn't exist."""
+        return self._storage.get(experience_id)
+
+    def delete(self, experience_id: str) -> bool:
+        """Delete an experience by id. Returns True if it existed."""
+        return self._storage.delete(experience_id)
+
+    def recent(self, n: int = 10) -> list[Experience]:
+        """Return the ``n`` most recently recorded experiences, newest first."""
+        return self._storage.recent(n)
+
+    def recommend(self, task: str, k: int = 20) -> Recommendation | None:
+        """Suggest a strategy for a new task by aggregating similar past
+        experiences. Returns None if there's nothing relevant to go on.
+
+        Confidence is the Wilson lower bound of the success rate for the
+        recommended action — so an action that worked 9/10 times outranks one
+        that worked 1/1 time (small samples are penalised, as they should be).
+        """
+        candidates = self._storage.search(task, k=k)
+        if not candidates:
+            return None
+
+        groups: dict[str, list[tuple[Experience, float]]] = defaultdict(list)
+        for exp, rel in candidates:
+            groups[_normalize(exp.action)].append((exp, rel))
+
+        best: Recommendation | None = None
+        for action_key, items in groups.items():
+            succ = sum(1 for e, _ in items if e.outcome is Outcome.SUCCESS)
+            fail = sum(1 for e, _ in items if e.outcome is Outcome.FAILURE)
+            part = sum(1 for e, _ in items if e.outcome is Outcome.PARTIAL)
+            total = len(items)
+            effective_successes = succ + 0.5 * part
+            confidence = _wilson_lower_bound(effective_successes, total)
+            # Use the most relevant phrasing of the action as the display string.
+            display_action = max(items, key=lambda pair: pair[1])[0].action
+            rec = Recommendation(
+                task=task,
+                recommended_action=display_action,
+                confidence=confidence,
+                success_count=succ,
+                failure_count=fail,
+                partial_count=part,
+                based_on=total,
+                supporting_ids=[e.id for e, _ in items],
+            )
+            if best is None or rec.confidence > best.confidence:
+                best = rec
+        return best
+
+    def _rerank(
+        self, query: str, candidates: list[tuple[Experience, float]]
+    ) -> list[tuple[Experience, float]]:
+        qvec = self._embedder.embed(query)
+        rescored = []
+        for exp, kw_score in candidates:
+            sem = cosine_similarity(qvec, exp.embedding) if exp.embedding else 0.0
+            # Blend keyword and semantic relevance.
+            rescored.append((exp, 0.5 * kw_score + 0.5 * sem))
+        rescored.sort(key=lambda pair: pair[1], reverse=True)
+        return rescored
+
+    # -- misc ---------------------------------------------------------------
+
+    def count(self) -> int:
+        return self._storage.count()
+
+    def close(self) -> None:
+        self._storage.close()
+
+    def __enter__(self) -> "Mimir":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+
+def _default_score(outcome: Outcome) -> float:
+    return {Outcome.SUCCESS: 1.0, Outcome.PARTIAL: 0.5, Outcome.FAILURE: 0.0}[outcome]
+
+
+def _normalize(action: str) -> str:
+    return " ".join(action.lower().split())
+
+
+def _wilson_lower_bound(successes: float, total: int, z: float = 1.96) -> float:
+    """Lower bound of a Wilson score interval for a binomial proportion.
+
+    Rewards both a high success rate and a large sample size.
+    """
+    if total == 0:
+        return 0.0
+    phat = successes / total
+    denom = 1 + z * z / total
+    centre = phat + z * z / (2 * total)
+    margin = z * math.sqrt((phat * (1 - phat) + z * z / (4 * total)) / total)
+    return max(0.0, (centre - margin) / denom)

mimir/embeddings.py

@@ -0,0 +1,39 @@
+"""Embedding provider seam.
+
+The default is a no-op: recall works on keywords alone, so v1 has no heavy
+dependencies and no API cost. Plug in a real embedder (local or API-backed) to
+enable semantic recall — it just needs to implement ``Embedder``.
+"""
+
+from __future__ import annotations
+
+import math
+from abc import ABC, abstractmethod
+
+
+class Embedder(ABC):
+    enabled: bool = True
+
+    @abstractmethod
+    def embed(self, text: str) -> list[float]:
+        """Return a vector for ``text``."""
+
+
+class NullEmbedder(Embedder):
+    """Does nothing. Recall falls back to keyword search."""
+
+    enabled = False
+
+    def embed(self, text: str) -> list[float]:  # pragma: no cover - never called
+        raise RuntimeError("NullEmbedder cannot produce embeddings")
+
+
+def cosine_similarity(a: list[float], b: list[float]) -> float:
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    if na == 0 or nb == 0:
+        return 0.0
+    return dot / (na * nb)

mimir/models.py

@@ -0,0 +1,89 @@
+"""Core data models for Mimir.
+
+The whole point of Mimir is that it stores *experiences* (problem -> action ->
+outcome), not documents. These models are that contract.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from enum import Enum
+
+from pydantic import BaseModel, Field, field_validator
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _new_id() -> str:
+    return uuid.uuid4().hex
+
+
+class Outcome(str, Enum):
+    """How an attempt turned out."""
+
+    SUCCESS = "success"
+    FAILURE = "failure"
+    PARTIAL = "partial"
+
+
+class Experience(BaseModel):
+    """A single recorded experience: what was attempted and how it went.
+
+    This is the atomic unit Mimir stores and learns from.
+    """
+
+    id: str = Field(default_factory=_new_id)
+    task: str  # the problem being solved
+    action: str  # what was actually done
+    outcome: Outcome = Outcome.SUCCESS
+    score: float = Field(default=1.0, ge=0.0, le=1.0)  # quality/confidence of the outcome
+    context: dict = Field(default_factory=dict)  # env, tags, agent_id, domain, ...
+    embedding: list[float] | None = None  # set only when an embedder is configured
+    created_at: datetime = Field(default_factory=_now)
+    superseded_by: str | None = None  # for staleness/versioning (future use)
+
+    @field_validator("task", "action")
+    @classmethod
+    def _not_blank(cls, value: str) -> str:
+        cleaned = value.strip()
+        if not cleaned:
+            raise ValueError("must not be empty or whitespace")
+        return cleaned
+
+    def text(self) -> str:
+        """The text Mimir indexes and embeds for retrieval."""
+        return f"{self.task}\n{self.action}"
+
+
+class Recommendation(BaseModel):
+    """A strategy suggested for a new task, derived from past experiences.
+
+    In v1 this is computed on the fly by aggregating recalled experiences
+    (no LLM). Later phases will materialize these as first-class Strategy rows.
+    """
+
+    task: str  # the query this recommendation answers
+    recommended_action: str
+    confidence: float = Field(ge=0.0, le=1.0)
+    success_count: int = 0
+    failure_count: int = 0
+    partial_count: int = 0
+    based_on: int = 0  # number of experiences considered
+    supporting_ids: list[str] = Field(default_factory=list)
+
+    @property
+    def total(self) -> int:
+        return self.success_count + self.failure_count + self.partial_count
+
+    def __str__(self) -> str:  # nice console output, as shown in the README
+        return (
+            f"Recommended strategy: {self.recommended_action!r}\n"
+            f"  confidence: {self.confidence:.2f}\n"
+            f"  based on {self.total} experiences "
+            f"({self.success_count} success / {self.failure_count} failure"
+            + (f" / {self.partial_count} partial" if self.partial_count else "")
+            + ")"
+        )

mimir/storage/__init__.py

@@ -0,0 +1,4 @@
+from .base import Storage
+from .sqlite import SQLiteStorage
+
+__all__ = ["Storage", "SQLiteStorage"]

mimir/storage/base.py

@@ -0,0 +1,52 @@
+"""Storage interface — the seam that lets Mimir swap backends without a rewrite.
+
+v1 ships a SQLite implementation. A Postgres/pgvector backend (for concurrent
+multi-agent writes) and adapters for external memory stores can implement this
+same interface later.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..models import Experience
+
+
+class Storage(ABC):
+    @abstractmethod
+    def add(self, exp: Experience) -> None:
+        """Persist a single experience."""
+
+    @abstractmethod
+    def get(self, experience_id: str) -> Experience | None:
+        """Fetch one experience by id, or None."""
+
+    @abstractmethod
+    def search(
+        self,
+        query: str,
+        k: int = 5,
+        outcome: str | None = None,
+        context: dict | None = None,
+    ) -> list[tuple[Experience, float]]:
+        """Return up to ``k`` (experience, relevance_score) pairs, best first.
+
+        ``relevance_score`` is in [0, 1]. ``outcome`` and ``context`` are
+        optional equality filters applied before ranking.
+        """
+
+    @abstractmethod
+    def delete(self, experience_id: str) -> bool:
+        """Remove one experience. Returns True if it existed."""
+
+    @abstractmethod
+    def recent(self, n: int = 10) -> list[Experience]:
+        """Return the ``n`` most recently recorded experiences, newest first."""
+
+    @abstractmethod
+    def count(self) -> int:
+        """Total number of stored experiences."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release any underlying resources."""

mimir/storage/sqlite.py

@@ -0,0 +1,230 @@
+"""SQLite storage backend — the v1 default.
+
+No external service required: the store is a single file (or in-memory). Keyword
+recall uses SQLite's FTS5 when available, and falls back to a portable
+Python token-overlap scorer when it isn't, so this works everywhere CPython does.
+
+The backend is internally thread-safe: every connection access is guarded by a
+lock, so reads and writes from multiple threads are serialized safely.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sqlite3
+import threading
+from datetime import datetime
+
+from ..models import Experience, Outcome
+from .base import Storage
+
+_TOKEN = re.compile(r"[a-z0-9]+")
+
+
+def _tokens(text: str) -> list[str]:
+    return _TOKEN.findall(text.lower())
+
+
+class SQLiteStorage(Storage):
+    def __init__(self, db_path: str = ":memory:") -> None:
+        if db_path not in (":memory:", "") and not db_path.startswith("file:"):
+            parent = os.path.dirname(os.path.abspath(db_path))
+            os.makedirs(parent, exist_ok=True)
+        # check_same_thread=False + an explicit lock lets the store be shared
+        # across threads safely.
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._lock = threading.RLock()
+        self._fts = self._init_schema()
+
+    # -- schema -------------------------------------------------------------
+
+    def _init_schema(self) -> bool:
+        with self._lock:
+            # WAL improves read/write concurrency and durability; NORMAL sync is
+            # the standard safe-and-fast pairing with WAL.
+            self._conn.execute("PRAGMA journal_mode=WAL")
+            self._conn.execute("PRAGMA synchronous=NORMAL")
+            self._conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS experiences (
+                    id            TEXT PRIMARY KEY,
+                    task          TEXT NOT NULL,
+                    action        TEXT NOT NULL,
+                    outcome       TEXT NOT NULL,
+                    score         REAL NOT NULL,
+                    context       TEXT NOT NULL,
+                    embedding     TEXT,
+                    created_at    TEXT NOT NULL,
+                    superseded_by TEXT
+                )
+                """
+            )
+            self._conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_experiences_outcome ON experiences(outcome)"
+            )
+            self._conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_experiences_created ON experiences(created_at)"
+            )
+            fts_ok = True
+            try:
+                self._conn.execute(
+                    "CREATE VIRTUAL TABLE IF NOT EXISTS experiences_fts "
+                    "USING fts5(id UNINDEXED, task, action)"
+                )
+            except sqlite3.OperationalError:
+                fts_ok = False  # FTS5 not compiled in — use the Python fallback
+            self._conn.commit()
+            return fts_ok
+
+    # -- writes -------------------------------------------------------------
+
+    def add(self, exp: Experience) -> None:
+        with self._lock:
+            self._conn.execute(
+                "INSERT OR REPLACE INTO experiences "
+                "(id, task, action, outcome, score, context, embedding, created_at, "
+                "superseded_by) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    exp.id,
+                    exp.task,
+                    exp.action,
+                    exp.outcome.value,
+                    exp.score,
+                    json.dumps(exp.context),
+                    json.dumps(exp.embedding) if exp.embedding is not None else None,
+                    exp.created_at.isoformat(),
+                    exp.superseded_by,
+                ),
+            )
+            if self._fts:
+                # Keep FTS in sync on re-record: clear any stale row for this id
+                # first, otherwise INSERT OR REPLACE above would leave a duplicate
+                # FTS entry and skew search results.
+                self._conn.execute("DELETE FROM experiences_fts WHERE id = ?", (exp.id,))
+                self._conn.execute(
+                    "INSERT INTO experiences_fts (id, task, action) VALUES (?, ?, ?)",
+                    (exp.id, exp.task, exp.action),
+                )
+            self._conn.commit()
+
+    def delete(self, experience_id: str) -> bool:
+        with self._lock:
+            cur = self._conn.execute(
+                "DELETE FROM experiences WHERE id = ?", (experience_id,)
+            )
+            if self._fts:
+                self._conn.execute(
+                    "DELETE FROM experiences_fts WHERE id = ?", (experience_id,)
+                )
+            self._conn.commit()
+            return cur.rowcount > 0
+
+    # -- reads --------------------------------------------------------------
+
+    def get(self, experience_id: str) -> Experience | None:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT * FROM experiences WHERE id = ?", (experience_id,)
+            ).fetchone()
+        return self._row_to_experience(row) if row else None
+
+    def recent(self, n: int = 10) -> list[Experience]:
+        with self._lock:
+            # Tie-break on rowid (monotonic insertion order) because created_at
+            # resolution can collide for records written in the same instant.
+            rows = self._conn.execute(
+                "SELECT * FROM experiences ORDER BY created_at DESC, rowid DESC LIMIT ?",
+                (n,),
+            ).fetchall()
+        return [self._row_to_experience(r) for r in rows]
+
+    def count(self) -> int:
+        with self._lock:
+            return self._conn.execute("SELECT COUNT(*) FROM experiences").fetchone()[0]
+
+    def search(
+        self,
+        query: str,
+        k: int = 5,
+        outcome: str | None = None,
+        context: dict | None = None,
+    ) -> list[tuple[Experience, float]]:
+        scored = self._fts_search(query) if self._fts else self._fallback_search(query)
+        results: list[tuple[Experience, float]] = []
+        for exp, score in scored:
+            if outcome is not None and exp.outcome.value != outcome:
+                continue
+            if context and not _context_matches(exp.context, context):
+                continue
+            results.append((exp, score))
+            if len(results) >= k:
+                break
+        return results
+
+    def _fts_search(self, query: str) -> list[tuple[Experience, float]]:
+        terms = _tokens(query)
+        if not terms:
+            return []
+        match = " OR ".join(f'"{t}"' for t in terms)
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT e.*, bm25(experiences_fts) AS rank "
+                "FROM experiences_fts "
+                "JOIN experiences e ON e.id = experiences_fts.id "
+                "WHERE experiences_fts MATCH ? "
+                "ORDER BY rank",  # bm25: lower is better
+                (match,),
+            ).fetchall()
+        out = []
+        for row in rows:
+            # bm25 is an unbounded negative-ish score; squash to (0, 1] for a stable API
+            rank = row["rank"]
+            score = 1.0 / (1.0 + max(rank, 0.0))
+            out.append((self._row_to_experience(row), score))
+        return out
+
+    def _fallback_search(self, query: str) -> list[tuple[Experience, float]]:
+        q = set(_tokens(query))
+        if not q:
+            return []
+        with self._lock:
+            rows = self._conn.execute("SELECT * FROM experiences").fetchall()
+        scored = []
+        for row in rows:
+            exp = self._row_to_experience(row)
+            doc = set(_tokens(exp.text()))
+            if not doc:
+                continue
+            overlap = len(q & doc)
+            if overlap == 0:
+                continue
+            score = overlap / len(q)  # fraction of query terms matched
+            scored.append((exp, score))
+        scored.sort(key=lambda pair: pair[1], reverse=True)
+        return scored
+
+    # -- helpers ------------------------------------------------------------
+
+    def _row_to_experience(self, row: sqlite3.Row) -> Experience:
+        return Experience(
+            id=row["id"],
+            task=row["task"],
+            action=row["action"],
+            outcome=Outcome(row["outcome"]),
+            score=row["score"],
+            context=json.loads(row["context"]),
+            embedding=json.loads(row["embedding"]) if row["embedding"] else None,
+            created_at=datetime.fromisoformat(row["created_at"]),
+            superseded_by=row["superseded_by"],
+        )
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+
+def _context_matches(stored: dict, wanted: dict) -> bool:
+    return all(stored.get(key) == value for key, value in wanted.items())

mimir_learn-0.1.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: mimir-learn
+Version: 0.1.0
+Summary: Experience-driven memory for autonomous agents — learn from past successes and failures.
+Project-URL: Homepage, https://github.com/AshNicolus/mimir
+Project-URL: Repository, https://github.com/AshNicolus/mimir
+Author: AshNicolus
+License: MIT License
+        
+        Copyright (c) 2026 AshNicolus
+        
+        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.
+License-File: LICENSE
+Keywords: agents,experience,learning,llm,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: numpy>=1.24; extra == 'embeddings'
+Requires-Dist: sentence-transformers>=2.2; extra == 'embeddings'
+Description-Content-Type: text/markdown
+
+# Mimir
+
+**Experience-driven memory for autonomous agents.** Mimir helps agents learn from their past successes and failures instead of starting from scratch on every task.
+
+> Named after Mímir, the keeper of wisdom in Norse mythology.
+
+---
+
+## The problem
+
+Today's agents have memory, but they don't really *learn*.
+
+Most frameworks store one of two things:
+
+- **Conversation history** (LangGraph memory, buffer memory)
+- **Vector embeddings of documents** (RAG, AGENTS.md, CLAUDE.md)
+
+Both let an agent **remember information**. Neither lets it **remember experience**.
+
+```
+Task:     Fix authentication latency
+Action:   Added Redis cache
+Outcome:  Success
+```
+
+A month later, the agent has no meaningful understanding that this strategy worked. It solves the same class of problem from zero, every time.
+
+## The idea
+
+Instead of storing documents, embeddings, and metadata, Mimir stores **experiences**:
+
+```
+Problem  →  Action  →  Outcome  →  Confidence  →  Context  →  Time
+```
+
+From a stream of experiences, Mimir reflects, extracts reusable strategies, and recommends actions for new tasks — so the agent gets measurably better over time.
+
+```python
+from mimir import Mimir
+
+memory = Mimir()
+
+# Record what happened
+memory.record(
+    task="Fix authentication timeout",
+    action="Implemented Redis caching",
+    outcome="success",
+    score=0.95,
+)
+
+# Recall relevant past experience
+past = memory.recall("authentication latency")
+
+# Get a recommended strategy with confidence
+strategy = memory.recommend("login timeout")
+# → Strategy: "Redis caching"  |  confidence: 0.87  |  based on 23 successes / 2 failures
+```
+
+## How it differs from AGENTS.md / CLAUDE.md
+
+| | AGENTS.md / CLAUDE.md | Mimir |
+|---|---|---|
+| Knowledge type | Static, hand-written rules | Dynamic, learned from outcomes |
+| Updates | Manually edited | Updates itself from results |
+| Example | "Use FastAPI. Use PostgreSQL." | "Redis caching solved auth latency 23/25 times (92%)." |
+| Failures | Not tracked | First-class — agents stop repeating mistakes |
+
+AGENTS.md answers *"What should the agent remember?"*
+Mimir answers *"How does an agent accumulate experience and become wiser over time?"*
+
+## Design principles
+
+Mimir is built as a **modular monolith Python library** — not a microservice swarm, not a managed cloud product. The library is the product.
+
+- **No LLM and no web server required for v1.** Storage, retrieval, and ranking come first. Reflection via an LLM is added later, behind an interface.
+- **Pluggable seams.** Storage, embeddings, and the write path are interfaces, so scaling up (SQLite → Postgres → async reflection → Redis cache) is a swap, never a rewrite.
+- **Derived knowledge is rebuildable.** Strategies and reflections are computed from raw experiences and can always be regenerated.
+- **Failures are first-class.** Learning from what *didn't* work is treated as importantly as what did.
+
+## Architecture
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  Public API   Mimir()  .record() .recall() .recommend()     │
+├────────────────────────────────────────────────────────────┤
+│  Write chokepoint   ──►  [validation / provenance hook]      │   single write path
+├──────────────┬───────────────┬─────────────────────────────┤
+│  Episodic    │  Reflection   │  Recommendation             │
+│  Engine      │  Engine       │  Engine                     │
+│  (record/    │  (reflect/    │  (recommend / rank /         │
+│   recall)    │   extract)    │   confidence)               │
+├──────────────┴───────────────┴─────────────────────────────┤
+│  Retrieval layer        (keyword + optional vector hybrid)   │
+├────────────────────────────────────────────────────────────┤
+│  Storage interface      SQLite (v1) · Postgres (v2) · …      │   pluggable
+├────────────────────────────────────────────────────────────┤
+│  Embedding provider     none (default) · local · API        │   pluggable
+└────────────────────────────────────────────────────────────┘
+```
+
+### Data model
+
+```
+Experience
+  id, task, action, outcome (success|failure|partial),
+  score (0..1), context (json), embedding (nullable),
+  created_at, superseded_by (nullable)
+
+Strategy   (derived)  problem_pattern, recommended_action, confidence,
+                      success_count, failure_count, source_experience_ids
+Reflection (derived)  summary, pattern, supporting_experience_ids, created_at
+```
+
+## Installation
+
+```bash
+pip install mimir   # (coming soon)
+
+# or, for development
+git clone https://github.com/<you>/mimir.git
+cd mimir
+pip install -e ".[dev]"
+```
+
+**Requirements:** Python 3.11+. v1 has no required external services — storage is a local SQLite file. Semantic search and reflection are optional extras.
+
+## Quick start
+
+```python
+from mimir import Mimir
+
+memory = Mimir(db_path="mimir.db")
+
+memory.record(
+    task="Fix login latency",
+    action="Added Redis cache in front of session lookups",
+    outcome="success",
+    score=0.9,
+    context={"service": "auth", "language": "python"},
+)
+
+memory.record_failure(
+    task="Throttle abusive clients",
+    action="Added a fixed-window rate limiter",
+    reason="WebSocket traffic wasn't handled — limiter only saw HTTP",
+)
+
+for exp in memory.recall("authentication is slow", k=5):
+    print(exp.action, exp.outcome, exp.score)
+
+print(memory.recommend("login times out under load"))
+```
+
+## Roadmap
+
+| Phase | Goal | Status |
+|---|---|---|
+| **1 — Episodic memory** | `record()` / `recall()`, outcome tracking, SQLite backend | 🛠️ In progress |
+| **2 — Failure memory** | `record_failure()`, failures queried separately | Planned |
+| **3 — Reflection engine** | `reflect()` — cluster experiences, synthesize patterns (LLM) | Planned |
+| **4 — Strategy extraction** | Turn experiences into reusable strategies with confidence | Planned |
+| **5 — Recommendation engine** | `recommend()` — rank strategies for a new task | Planned |
+| **6 — Shared org memory** | Multiple agents learn from a shared store | Future |
+
+## Scaling path
+
+Mimir starts as a single SQLite file and grows by swapping seams — no rewrites:
+
+1. **v1** — SQLite, in-process, single agent.
+2. **v2** — Postgres + pgvector backend for concurrent multi-agent writes.
+3. **v3** — extract the (slow, batch) reflection engine into an async worker.
+4. **v4** — Redis cache for hot/recent experiences on the read path.
+
+## Status
+
+Early development. APIs will change. Not yet published to PyPI. Feedback and ideas welcome.
+
+## License
+
+MIT

mimir_learn-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mimir/__init__.py,sha256=hnxZwiW7O66Irie92SOHgQmrETq0qbzI_iBDpIhoq84,414
+mimir/core.py,sha256=7qRzgdzVYJ7HywydvLvwnazpzxiQzz15zGLU9XqmR1w,7497
+mimir/embeddings.py,sha256=pbEifuCYUKCvphSfSGv28_Qr0ndcCfJmM99u2YZHeQA,1094
+mimir/models.py,sha256=9o6oDc8gap6x3iiHUZ7auv8HIRG-UXjF4iKGf7IVrDA,2878
+mimir/storage/__init__.py,sha256=FkN7CtMvJIUTNMbVLD_LIAVqqTfKQDk5bQTTfAOKrRQ,100
+mimir/storage/base.py,sha256=xmyiNiqc1gA6kX6iNzqQrbZJdXTdMmg0IO3iT7ENMKQ,1553
+mimir/storage/sqlite.py,sha256=uubY4BpuvPWa-vVbITUhRTiSCt_lJfmzPk2vqIDAu_s,8895
+mimir_learn-0.1.0.dist-info/METADATA,sha256=nUciuXZVQsx-o_hwi4naYA9I_5eW88qTZ7W0UOvekB4,9716
+mimir_learn-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+mimir_learn-0.1.0.dist-info/licenses/LICENSE,sha256=BeqLZ3TPJtSjsBWSUtp9a_OLBnlQP111ATLC_JCxXG4,1067
+mimir_learn-0.1.0.dist-info/RECORD,,

mimir_learn-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

mimir_learn-0.1.0.dist-info/licenses/LICENSE

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