Metadata-Version: 2.4
Name: mnemonic-ai
Version: 0.1.0
Summary: Framework-agnostic memory layer for AI agents with importance-aware, graph-structured context assembly
Author: Mnemonic Contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/obscura-oss/mnemonic-oss
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: local-embeddings
Requires-Dist: sentence-transformers>=2.2; extra == "local-embeddings"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == "postgres"
Requires-Dist: pgvector>=0.2; extra == "postgres"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1; extra == "langchain"
Provides-Extra: crewai
Requires-Dist: crewai>=0.1; extra == "crewai"
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2; extra == "autogen"
Provides-Extra: openai-embeddings
Requires-Dist: openai>=1.0; extra == "openai-embeddings"
Provides-Extra: anthropic-embeddings
Requires-Dist: anthropic>=0.18; extra == "anthropic-embeddings"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: mnemonic-ai[langchain,local-embeddings,mcp,postgres]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: ruff<1.0,>=0.4; extra == "dev"
Provides-Extra: benchmark
Requires-Dist: mnemonic-ai[openai-embeddings]; extra == "benchmark"
Requires-Dist: openai>=1.0; extra == "benchmark"
Requires-Dist: nltk>=3.8; extra == "benchmark"
Requires-Dist: gdown>=4.7; extra == "benchmark"
Requires-Dist: tqdm>=4.65; extra == "benchmark"
Dynamic: license-file

# Mnemonic

**Give your AI agents a memory that works like a brain.**

Today's AI agents are stateless. Every conversation starts from zero. Mnemonic changes that. It's a memory layer that models how humans actually remember — important things stick, old things fade, related ideas connect, and contradictions get flagged.

Tell your agent you prefer Kubernetes on Monday, and it still knows on Friday. Correct a mistake, and the old fact fades while the new one takes priority. No more repeating yourself.

## How It Works

Mnemonic organizes memories into **five tiers**, just like the human brain:

| Tier | What it holds | How long it lasts |
|------|--------------|-------------------|
| **Identity** | Name, role, core preferences | Years |
| **Procedural** | Workflows, step-by-step processes | ~1 year |
| **Structural** | Architecture decisions, tools, constraints | ~6 months |
| **Episodic** | Specific conversations and events | ~30 days |
| **Transient** | Small talk, temporary context | ~7 days |

Memories don't just sit in a list. They form a **graph** — related ideas link together, contradictions are detected, and outdated facts get superseded (not deleted). When your agent needs context, Mnemonic picks the most relevant memories that fit within the token budget.

## Get Started in 3 Lines

```bash
pip install mnemonic-ai
```

```python
from mnemonic import Mnemonic

mem = Mnemonic()
mem.add("User prefers dark mode and Kubernetes over ECS")
context = mem.recall("deployment preferences", max_tokens=3000)
# Returns the most relevant memories, ranked by importance
```

No API keys. No database setup. Works immediately with SQLite.

## Why Mnemonic

- **Memories decay naturally** — like human memory, unused information fades. Actively accessed memories stay strong.
- **Smart prioritization** — urgency, errors, corrections, and decisions automatically get importance boosts.
- **Contradictions are handled** — "moved to SF" supersedes "lived in NYC" instead of creating confusion.
- **Stays within your token budget** — fills the context window with the highest-signal memories, not everything.
- **Gets smarter over time** — episodic memories consolidate into durable knowledge, just like sleep does for the brain.

## Scale When You're Ready

| What you need | How to get it |
|--------------|---------------|
| Production database | `pip install mnemonic-ai[postgres]` — PostgreSQL with vector search |
| Semantic search | `pip install mnemonic-ai[openai-embeddings]` or `mnemonic-ai[local-embeddings]` |
| AI tool integration | `pip install mnemonic-ai[mcp]` then `mnemonic-mcp` — works with Claude, VS Code Copilot |
| TypeScript | `npm install @mnemonic-ai/core` — full parity with Python |
| Multiple agents | Built-in agent isolation with explicit sharing |

## Use With Any Framework

```python
# LangChain
from mnemonic.adapters.langchain import LangChainMemory

# CrewAI
from mnemonic.adapters.crewai import CrewAIMemory

# AutoGen
from mnemonic.adapters.autogen import AutoGenMemory

# Or just inject into any prompt
from mnemonic.adapters.raw import recall_as_prompt
system = f"You are helpful.\n\n{recall_as_prompt(mem, user_query)}"
```

## Multi-Agent Memory

Multiple agents can share a memory store while keeping their own memories private:

```python
agent_a = Mnemonic(store=store, agent_id="researcher")
agent_b = Mnemonic(store=store, agent_id="coder")

agent_a.add("The API uses OAuth 2.0", shared=True)  # both agents see this
agent_b.add("Refactored auth module yesterday")       # only coder sees this
```

## Extend It

Mnemonic is designed to be extended. Register custom store backends, add consolidation hooks, or replace any heuristic with your own logic:

```python
from mnemonic import register_store, MnemonicConfig

register_store("mydb", my_factory)        # custom store backend

cfg = MnemonicConfig()
cfg.scorer.weight_recency = 0.50          # tune scoring weights
cfg.classifier.custom_classifier = my_fn  # replace tier classification
```

## Mnemonic Platform

Need Neo4j graph storage, LLM-powered consolidation, a REST API with authentication, or an admin dashboard? See [Mnemonic Platform](https://mnemonic-ai.dev).

## License

Apache 2.0
