Metadata-Version: 2.4
Name: mnemosynth
Version: 1.0.0
Summary: Universal AI Memory Plugin — persistent, verified, hallucination-resistant memory for any LLM, agent, or coding workflow
Project-URL: Homepage, https://github.com/vasudevjaiswal/mnemosynth
Project-URL: Repository, https://github.com/vasudevjaiswal/mnemosynth
Project-URL: Documentation, https://github.com/vasudevjaiswal/mnemosynth#readme
Project-URL: Issues, https://github.com/vasudevjaiswal/mnemosynth/issues
Project-URL: Changelog, https://github.com/vasudevjaiswal/mnemosynth/blob/main/CHANGELOG.md
Author-email: Vasudev Jaiswal <vasudevjaiswal@protonmail.com>
Maintainer-email: Vasudev Jaiswal <vasudevjaiswal@protonmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,belief-revision,cognitive,contradiction-detection,hallucination,knowledge-graph,llm,mcp,memory,rag,second-brain,vector-db
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: lancedb>=0.15
Requires-Dist: mcp>=1.0
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.24
Requires-Dist: pyarrow>=14.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.4; extra == 'ml'
Requires-Dist: sentence-transformers>=3.0; extra == 'ml'
Requires-Dist: transformers>=4.40; extra == 'ml'
Provides-Extra: production
Requires-Dist: falkordb>=1.0; extra == 'production'
Requires-Dist: qdrant-client>=1.9; extra == 'production'
Requires-Dist: redis>=5.0; extra == 'production'
Description-Content-Type: text/markdown

# 🧠 Mnemosynth

**Persistent, hallucination-resistant memory for any LLM, agent, or AI workflow.**

```bash
pip install mnemosynth       # Fast, lightweight install (Keyword-based engines)
pip install "mnemosynth[ml]" # Advanced install (Loads PyTorch/Transformers for Neural Models)
```

PyPI · Apache 2.0 · Python ≥ 3.10 · No external services required

---

## The Problem

LLMs forget everything when a session ends. RAG helps — but raw retrieval doesn't verify, decay, or reason about what it stores. You get confident hallucinations, stale facts, and no audit trail.

**Mnemosynth is a cognitive memory OS, not a vector store.**

---

## Three-Tier Memory Model

Inspired by how the brain actually works:

| Tier | Brain Region | Backend | What It Stores |
|---|---|---|---|
| **Episodic** | Hippocampus | LanceDB (vector) | Events, conversations, timestamped history |
| **Semantic** | Neocortex | NetworkX (graph) | Verified facts, entity relationships |
| **Procedural** | Cerebellum | JSON registry | Tools, schemas, workflows |

Memories are **automatically classified** on write. No manual tagging required.

---

## Quickstart

### Python API

```python
from mnemosynth import Mnemosynth

brain = Mnemosynth()

# Store — auto-classified into episodic/semantic/procedural
brain.remember("User prefers Python and dark mode")
brain.remember("Yesterday we finalized the auth module")
brain.remember("Deploy with: docker compose up -d")

# Retrieve with semantic search
for r in brain.recall("What languages does the user prefer?"):
    print(f"[{r.memory_type.value}] {r.content} ({r.confidence:.0%})")

# Compress relevant memories into a <150-token LLM context block
digest = brain.digest("Starting a new project")

# Dream: cluster episodic patterns -> promote to verified semantic facts
brain.dream()
```

### MCP Server (Claude Desktop / Cursor / Windsurf)

```json
{
  "mcpServers": {
    "mnemosynth": {
      "command": "mnemosynth",
      "args": ["serve"]
    }
  }
}
```

Everything runs locally under `~/.mnemosynth/`. No external services.

---

## Anti-Hallucination Engine

Mnemosynth doesn't just store — it **defends**:

- **Forgetting curve** — Ebbinghaus decay with configurable half-life; stale memories lose confidence
- **Contradiction detection** — Flags conflicting facts (*Uses DeBERTa NLI if `[ml]` is installed, otherwise falls back to fast keyword analysis*)
- **Sentiment analysis** — Emotion-aware memory retrieval (*Uses DistilBERT if `[ml]` is installed, otherwise falls back to fast keyword scoring*)
- **Belief revision chains** — Deprecated facts link forward to their replacements
- **Corroboration scoring** — Repeated observations boost confidence
- **Memory immune system** — Prompt injection detection, rate limiting, quarantine

---

## Dream Consolidation

Run `brain.dream()` (or `mnemosynth dream`) to trigger offline consolidation:

1. **Cluster** episodic memories with HDBSCAN
2. **Promote** recurring patterns to verified semantic facts
3. **Decay** memories that haven't been accessed recently

Think of it as sleep for your AI's memory.

---

## MCP Tools

| Tool | Description |
|---|---|
| `add_memory` | Store with auto-classification |
| `search_memory` | Semantic search across all tiers |
| `get_digest` | Compressed XML context block for LLM injection |
| `get_contradictions` | Surface conflicting facts |
| `run_dream` | Trigger consolidation |
| `forget` | Delete by ID |
| `get_stats` | Memory statistics |
| `get_provenance` | Full audit trail for any memory |

---

## CLI

```bash
mnemosynth serve              # Start MCP server
mnemosynth stats              # Memory dashboard
mnemosynth search "query"     # Semantic search
mnemosynth inspect            # Browse memory tree
mnemosynth dream              # Run consolidation
mnemosynth health             # System diagnostics
mnemosynth export -o out.json # Export to JSON or Markdown
mnemosynth forget <ID>        # Delete a memory
mnemosynth reset --confirm    # Wipe everything
```

---

## Configuration

Override defaults at `~/.mnemosynth/config.yaml`:

```yaml
embedding_model: all-MiniLM-L6-v2
max_episodic_memories: 10000
max_semantic_nodes: 5000

decay:
  half_life_days: 30.0
  min_confidence: 0.1

dream:
  interval_hours: 24
  min_cluster_size: 3

digest:
  max_tokens: 150
  top_k: 5
```

---

## Architecture

```
Claude Desktop / Cursor / Windsurf / Python API
              |  MCP (stdio) / Python import
     Router · Digest · Decay · Dream
     Sentiment · Contradiction · Immune System
              |
  Episodic (LanceDB) · Semantic (NetworkX) · Procedural (JSON)
              |
         ~/.mnemosynth/
```

---

Built by [Vasudev Jaiswal](https://github.com/vasudevjaiswal) · Apache 2.0