Metadata-Version: 2.4
Name: mnemoria
Version: 0.1.0
Summary: Cognitive memory system for AI agents — ACT-R activation, typed facts, Hebbian links, RL reranking
Project-URL: Homepage, https://github.com/Tranquil-Flow/mnemoria
Project-URL: Repository, https://github.com/Tranquil-Flow/mnemoria
Project-URL: Documentation, https://github.com/Tranquil-Flow/mnemoria#readme
Author: Tranquil-Flow
License: AGPL-3.0-or-later
License-File: LICENSE
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
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 :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Provides-Extra: all
Requires-Dist: httpx>=0.24.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == 'embeddings'
Provides-Extra: ollama
Requires-Dist: httpx>=0.24.0; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# Mnemoria

Cognitive memory system for AI agents — ACT-R activation, typed facts, Hebbian links, RL reranking.

## Installation

```bash
pip install mnemoria
```

## Quick Start

```python
from mnemoria.store import MnemoriaStore
from mnemoria.config import MnemoriaConfig

store = MnemoriaStore(MnemoriaConfig.balanced())
store.store("V[api.url]: https://example.com")
results = store.recall("What is the API URL?")
```

For better semantic recall on a real machine, install the embeddings extra:

```bash
pip install 'mnemoria[embeddings]'
```

Note: in constrained containers, TF-IDF fallback is expected and benchmark results may be lower than on a local machine with real embeddings.

## Features

- **ACT-R Activation** — Frequency + recency based activation scoring
- **Typed Facts** — MEMORY_SPEC notation (C/D/V/?/✓/~) with metabolic decay rates
- **Hebbian Links** — NPMI-normalized co-occurrence edges with Ebbinghaus decay
- **RL Reranking** — Q-value UCB-Tuned exploration bonus
- **Self-Optimizing Pipeline** — LinUCB bandits per retrieval stage
- **Scope Lifecycle** — active → cold → closed with gauge pressure management
- **Contradiction Detection** — Entity overlap + update language pattern matching
- **IPS Debiasing** — Inverse propensity scoring to counteract popularity bias
- **PPR Exploration** — Personalized PageRank multi-hop discovery

## Migration

If you are moving from Honcho or another external memory provider, see:
- `MIGRATING_FROM_HONCHO.md`

## Acknowledgements

If you want the provenance of ideas and inspirations, see:
- `ACKNOWLEDGEMENTS.md`

## License

AGPL-3.0-or-later — see LICENSE file or <https://www.gnu.org/licenses/agpl-3.0.html>