mhn-ai-agent-memory

<div align="center">

# MHN AI Agent Memory

### Associative Memory for AI Agents Using Modern Hopfield Networks

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-43%20passing-brightgreen.svg)](#development)
[![arXiv](https://img.shields.io/badge/arXiv-2008.02217-b31b1b.svg)](https://arxiv.org/abs/2008.02217)

**A Python library for deterministic associative memory in AI agents.**

[Install](#install) &#8226; [Quick Start](#30-second-example) &#8226; [Features](#features-at-a-glance) &#8226; [How It Works](#how-it-works-plain-english) &#8226; [API Reference](#project-structure)

</div>

---

<div align="center">

```
          ┌─────────────────────────────────────────────┐
          │                                             │
          │   xi_new = X @ softmax( beta * X^T @ xi )  │
          │                                             │
          │   One equation. One matrix multiply.        │
          │   Deterministic. Microseconds. Free.        │
          │                                             │
          └─────────────────────────────────────────────┘
```

</div>

---

## What is this?

Many agent memory systems store text in a database, then ask an LLM to interpret it at query time. This library does something else: it applies the [Modern Hopfield Network](https://arxiv.org/abs/2008.02217) update rule directly, exposing transformer-style attention as an explicit, controllable memory.

1. Store text in a database
2. Call an LLM to reason about it (costs money, takes seconds, non-deterministic)
3. Hope the LLM doesn't hallucinate about what it stored

| | Traditional (LLM + DB) | This Library |
|---|---|---|
| **Retrieval** | LLM API call | One matrix multiply |
| **Latency** | Seconds | Microseconds |
| **Cost** | Per-token | Zero after storage |
| **Determinism** | Non-d