Metadata-Version: 2.4
Name: antaris-memory
Version: 0.1.0
Summary: Human-like memory for AI agents. Patent pending.
Author-email: Antaris Analytics <moro@antarisanalytics.ai>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Antaris1337/antaris-memory
Project-URL: Documentation, https://memory.antarisanalytics.ai
Project-URL: Repository, https://github.com/Antaris1337/antaris-memory
Keywords: ai,memory,agents,llm,persistence,recall
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: embeddings
Requires-Dist: openai>=1.0; extra == "embeddings"
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == "all"
Dynamic: license-file

# 🧠 Antaris Memory

**Human-like memory for AI agents. Patent pending.**

Give your AI agents persistent memory that decays, reinforces, feels, reasons about time, detects its own contradictions, and cleans up after itself. For under $5/year.

[![Patent Pending](https://img.shields.io/badge/Patent-Pending-blue)](https://antarisanalytics.ai)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-green.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-orange.svg)](LICENSE)

## The Problem

Every AI agent forgets everything between sessions. GPT, Claude, Gemini — they all start from zero every time. Enterprise memory solutions cost $5,000-$50,000/year and provide basic retrieval at best.

## The Solution

```python
from antaris_memory import MemorySystem

# Initialize
mem = MemorySystem("./my-agent-workspace")

# Ingest conversations, notes, anything
mem.ingest_file("conversation.md", category="tactical")
mem.ingest_directory("./memory", pattern="*.md", category="tactical")

# Search with decay-weighted relevance
results = mem.search("what did we decide about pricing?")

# Ask about time
memories = mem.on_date("2026-02-14")
story = mem.narrative(topic="patent filing")

# Forget things (GDPR-ready)
mem.forget(entity="John Doe")
mem.forget(before_date="2025-01-01")

# Run dream-state consolidation
report = mem.consolidate()

# Save
mem.save()
```

## Features

| Feature | Description | Patent Claim |
|---------|-------------|-------------|
| **Memory Decay** | Ebbinghaus-inspired forgetting curves with reinforcement on access | Claim 16 |
| **Sentiment Tagging** | Auto-detect emotional context (positive, negative, urgent, strategic, financial) | Claim 17 |
| **Temporal Reasoning** | Query by date, date ranges, build chronological narratives | Claim 22 |
| **Confidence Scoring** | Track reliability, increase on corroboration | Claim 23 |
| **Contradiction Detection** | Flag when memories conflict with each other | Claim 23 |
| **Memory Compression** | Auto-summarize old files, preserve key points | Claim 20 |
| **Selective Forgetting** | GDPR-ready deletion by topic, entity, or date with audit trail | Claim 21 |
| **Dream State** | Background consolidation: find duplicates, cluster topics, generate insights | Claim 24 |

## Install

```bash
pip install antaris-memory
```

Or from source:

```bash
git clone https://github.com/Antaris1337/antaris-memory.git
cd antaris-memory
pip install -e .
```

## Quick Start

```python
from antaris_memory import MemorySystem

# Create a memory system
mem = MemorySystem("./workspace", half_life=7.0)

# Load existing state (if any)
mem.load()

# Ingest some content
mem.ingest("Today we decided to use PostgreSQL for the database.", 
           source="meeting-notes", category="strategic")

mem.ingest("The API costs $500/month which is too expensive.",
           source="review", category="financial")

# Search
results = mem.search("database decision")
for r in results:
    print(f"[{r.confidence:.1f}] {r.content}")

# Check stats
print(mem.stats())

# Save state
mem.save()
```

## How It Works

### Memory Decay (Ebbinghaus Curves)

Memories naturally fade over time, just like human memory:

```
Score = Importance × 2^(-age / half_life) + reinforcement
```

- **Fresh memories** score high
- **Old unused memories** fade toward zero
- **Accessed memories** get reinforced — the more you recall something, the stronger it stays
- Memories below the archive threshold are candidates for compression

### Sentiment Analysis

Every memory is auto-tagged with emotional context:

```python
entry.sentiment = {"positive": 0.8, "financial": 0.5}
```

Search by emotion: `mem.search("budget", sentiment_filter="financial")`

### Dream State Consolidation

Run periodically (cron job, background task) to:
- Find and merge near-duplicate memories
- Discover topic clusters
- Detect contradictions
- Suggest memories for archival

```python
report = mem.consolidate()
# Returns: duplicates found, clusters, contradictions, archive suggestions
```

## Architecture

```
┌─────────────────────────────────────────────┐
│              MemorySystem                    │
│                                             │
│  ┌──────────┐ ┌───────────┐ ┌────────────┐ │
│  │  Decay   │ │ Sentiment │ │  Temporal   │ │
│  │  Engine  │ │  Tagger   │ │  Engine     │ │
│  └──────────┘ └───────────┘ └────────────┘ │
│  ┌──────────┐ ┌───────────┐ ┌────────────┐ │
│  │Confidence│ │Compression│ │ Forgetting  │ │
│  │  Engine  │ │  Engine   │ │  Engine     │ │
│  └──────────┘ └───────────┘ └────────────┘ │
│  ┌──────────────────────────────────────┐   │
│  │     Consolidation Engine             │   │
│  │     (Dream State Processing)         │   │
│  └──────────────────────────────────────┘   │
│                                             │
│  Storage: JSON file (zero dependencies)     │
└─────────────────────────────────────────────┘
```

## Configuration

```python
mem = MemorySystem(
    workspace="./workspace",    # Where to store metadata
    half_life=7.0,              # Memory decay half-life in days
    tag_terms=["custom", "terms"],  # Additional auto-tag keywords
)
```

## Zero Dependencies

Antaris Memory uses only Python standard library. No numpy, no torch, no API keys required.

**Optional:** Install `openai` for embedding-based semantic search (coming in v0.2).

## Comparison

| Feature | Antaris Memory | LangChain Memory | Mem0 | Zep |
|---------|---------------|-----------------|------|-----|
| Memory decay curves | ✅ | ❌ | ❌ | ❌ |
| Emotional tagging | ✅ | ❌ | ❌ | ❌ |
| Temporal reasoning | ✅ | ❌ | ❌ | ❌ |
| Contradiction detection | ✅ | ❌ | ❌ | ❌ |
| Selective forgetting | ✅ | ❌ | ❌ | ❌ |
| Dream state consolidation | ✅ | ❌ | ❌ | ❌ |
| Zero dependencies | ✅ | ❌ | ❌ | ❌ |
| Cost per year | <$5 | $500+ | $500+ | $1000+ |
| Patent protected | ✅ | ❌ | ❌ | ❌ |

## License

Apache 2.0 — free for personal and commercial use.

The underlying technology is protected by US Patent Application #63/983,397 (pending). Commercial products that implement the patented methods require a commercial license from Antaris Analytics.

## Built by

**Antaris Analytics** — AI memory intelligence  
📧 moro@antarisanalytics.ai  
🌐 [antarisanalytics.ai](https://antarisanalytics.ai)

---

*"We gave AI agents human-like memory for $5/year."*
