mimir-learn 0.1.0__tar.gz

mimir_learn-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint (ruff)
+        run: ruff check .
+      - name: Test (pytest)
+        run: pytest -q

mimir_learn-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+# Publishes when you create a GitHub Release. Uses PyPI Trusted Publishing
+# (OIDC) — no API tokens are stored anywhere.
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build & test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip build
+          pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q
+      - name: Build distributions
+        run: python -m build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

mimir_learn-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Mimir local data
+*.db
+*.db-journal
+*.sqlite
+*.sqlite3
+
+# Testing / tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

mimir_learn-0.1.0/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.

mimir_learn-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,180 @@
+# 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/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mimir-learn"
+version = "0.1.0"
+description = "Experience-driven memory for autonomous agents — learn from past successes and failures."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [{ name = "AshNicolus" }]
+keywords = ["agents", "memory", "llm", "experience", "learning"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "pydantic>=2.5",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.5"]
+# Local semantic search (optional). Keyword recall works without this.
+embeddings = ["sentence-transformers>=2.2", "numpy>=1.24"]
+
+[project.urls]
+Homepage = "https://github.com/AshNicolus/mimir"
+Repository = "https://github.com/AshNicolus/mimir"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mimir"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

mimir_learn-0.1.0/src/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",
+]