Metadata-Version: 2.1
Name: vividmimir
Version: 1.0.1
Summary: The Ultimate Memory Architecture — 21 neuroscience mechanisms orchestrating VividnessMem + VividEmbed
Author: Kronic90
License: PolyForm-Noncommercial-1.0.0
Project-URL: Homepage, https://github.com/Kronic90/Mimir
Project-URL: Repository, https://github.com/Kronic90/Mimir
Project-URL: Issues, https://github.com/Kronic90/Mimir/issues
Keywords: ai,memory,llm,agent,neuroscience,episodic-memory,organic-memory,flashbulb,reconsolidation,spaced-repetition,hippocampal,spreading-activation,conversational-ai,companion
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: engines
Requires-Dist: vividnessmem>=1.0.8; extra == "engines"
Requires-Dist: vividembed>=1.0.1; extra == "engines"
Provides-Extra: visual
Requires-Dist: Pillow>=10.0; extra == "visual"
Provides-Extra: encryption
Requires-Dist: cryptography>=41.0; extra == "encryption"
Provides-Extra: all
Requires-Dist: vividnessmem>=1.0.8; extra == "all"
Requires-Dist: vividembed>=1.0.1; extra == "all"
Requires-Dist: Pillow>=10.0; extra == "all"
Requires-Dist: cryptography>=41.0; extra == "all"

# Mimir — The Ultimate Memory Architecture

<p align="center">
  <img src="https://raw.githubusercontent.com/Kronic90/Mimir/main/MimirLogo.png" alt="Mímir Logo" width="300">
</p>

[![PyPI](https://img.shields.io/pypi/v/vividmimir)](https://pypi.org/project/vividmimir/)
[![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm--NC-blue)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)

**21 neuroscience mechanisms** orchestrating [VividnessMem](https://pypi.org/project/vividnessmem/) and [VividEmbed](https://pypi.org/project/vividembed/) into a unified memory system for AI agents and companions.

> Named for the Norse god of wisdom who drank from the well of knowledge beneath Yggdrasil.

## Key Features

| Mechanism | Citation |
|---|---|
| Flashbulb Memory | Brown & Kulik 1977 |
| Reconsolidation | Nader et al 2000 |
| State-Dependent Memory | Godden & Baddeley 1975 |
| Spreading Activation | Collins & Loftus 1975 |
| Retrieval-Induced Forgetting | Anderson 1994 |
| Zeigarnik Effect | Zeigarnik 1927 |
| Involuntary Recall | Berntsen 2009 |
| Temporal Gist | Reyna & Brainerd 1995 |
| Temporal / Episodic | Tulving 1972 |
| Visual / Mental Imagery | Kosslyn 1980 / Paivio 1986 |
| Huginn (Thought) | Pattern detection |
| Muninn (Memory) | Consolidation daemon |
| Yggdrasil (World Tree) | Memory graph |
| Völva's Vision | Dream synthesis |
| Novelty-Modulated Encoding | Ranganath & Rainer 2003 |
| Enhanced Drift Analysis | Cognitive bias detection |
| Hippocampal Pattern Separation | Computational neuroscience |
| Narrative Arc Tracking | Story structure |
| Task / Project Branch | Project memory |
| Hybrid Retrieval Bridge | BM25 + semantic + date + 5-signal re-rank |
| Encryption at Rest | Fernet + PBKDF2 |

## Installation

```bash
# Core (zero required dependencies — everything degrades gracefully)
pip install vividmimir

# With the full Vivid engine stack
pip install vividmimir[all]

# Individual extras
pip install vividmimir[engines]      # VividnessMem + VividEmbed
pip install vividmimir[visual]       # Pillow for mental-imagery system
pip install vividmimir[encryption]   # Fernet encryption at rest
```

## Quick Start

```python
from vividmimir import Mimir

m = Mimir(data_dir="my_mind")

# Store a memory
mem = m.remember("We talked about the northern lights in Iceland", "awe", 9)

# Retrieve context for an LLM
ctx = m.get_memory_context("Tell me about our travel plans")
print(ctx)

# Build a full context block (memories + emotions + lessons + tasks)
block = m.build_context_block("What were we discussing?")
```

## Memory Types

- **Episodic** — event memories with emotion, vividness, and organic decay
- **Social Profiles** — per-person relationship tracking
- **Procedural / Lessons** — strategies learned from experience
- **Volatile / Short-Term** — facts that expire automatically
- **Prospective / Reminders** — time or context-triggered future actions
- **Visual** — mental imagery with Pillow integration
- **Task / Project** — branch-aware project memory

## Part of the Vivid Ecosystem

| Package | Role |
|---|---|
| [vividnessmem](https://pypi.org/project/vividnessmem/) | Neurochemistry engine — organic decay, spaced repetition, emotion |
| [vividembed](https://pypi.org/project/vividembed/) | 389-d hybrid embeddings — semantic retrieval with emotion dimensions |
| **vividmimir** | Orchestrator — 21 mechanisms, hybrid retrieval, full memory architecture |

## Documentation

Full API reference, benchmark results, and architecture details:
**[github.com/Kronic90/Mimir](https://github.com/Kronic90/Mimir)**

## License

[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) — free for personal and research use. Commercial use requires a separate license. Contact: [GitHub Issues](https://github.com/Kronic90/Mimir/issues).
