mnemosyne-memory 1.9.0__tar.gz

mnemosyne_memory-1.9.0/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+Mnemosyne uses [Simple Versioning](https://gist.github.com/jonlow/6f7610566408a8efaa4a):
+given a version number **MAJOR.MINOR**, increment the:
+
+- **MINOR** after every iteration of development, testing, and quality assurance.
+- **MAJOR** for the first production release (1.0) or for significant new functionality (2.0, 3.0, etc.).
+
+---
+
+## 1.8
+
+- Fix Hermes plugin CLI discovery: add `register(ctx)` to wire up `hermes mnemosyne stats|sleep|inspect|clear|export|import|version`
+- README: clarify deploy script vs pip install paths (Option A / Option B)
+
+## 1.7
+
+- Fix subagent context writes polluting persistent memory (PR #8 by @woaim65)
+- Fix cross-session recall inconsistency: global memories now survive consolidation with scope preserved
+- Fix fallback keyword scoring for Chinese and spaceless languages (character-level overlap)
+- Fix episodic memory having no fallback scan when vector search and FTS5 both miss
+- Fix plugin tools singleton using stale session_id across sessions
+- Add regression tests: subagent context safety, cross-session recall, Chinese substring matching, session singleton updates
+
+## 1.6
+
+- Feature request issue template
+- Documentation improvement issue template
+- Issue template config with links to Discussions and Security advisories
+
+## 1.5
+
+- Fix 6 critical bugs from issue #6 (stats, recall tracking, vector similarity, missing methods, hardcoded session_id)
+- Fix fastembed dependency in setup.py and README (was incorrectly listing sentence-transformers)
+- Official bug report issue template
+- Adopt simplified MAJOR.MINOR versioning
+
+## 1.4
+
+- Full README rewrite: professional, community-focused, benchmarks restored
+- CONTRIBUTING.md added
+- FluxSpeak branding scrubbed (author/metadata corrected)
+- Project image banner added
+
+## 1.3
+
+- Export / import memory for cross-machine migration
+- CLI subcommands: `export`, `import`, `version`
+
+## 1.2
+
+- Mnemosyne as deployable MemoryProvider via Hermes plugin system
+- One-command installer (`python -m mnemosyne.install`)
+- CLI fix: `register_cli` correctly handles subparsers
+
+## 1.1
+
+- Dense retrieval via fastembed (bge-small-en-v1.5)
+- Temporal validity + global scope (`scope="global"`)
+- Recall tracking + recency decay scoring
+- Exact-match deduplication in working memory
+- Local LLM-based sleep consolidation (TinyLlama fallback)
+- BEAM scale limits for 1M+ token capacity
+
+## 1.0
+
+First major release. Production-ready.
+
+- BEAM architecture: working_memory, episodic_memory, scratchpad
+- Native vector search via sqlite-vec (HNSW-style)
+- FTS5 full-text hybrid search (50% vector + 30% FTS + 20% importance)
+- Temporal triples (time-aware knowledge graph)
+- AAAK context compression
+- Configurable vector compression: float32, int8, bit
+- Hermes plugin integration
+- Sub-millisecond latency on CPU

mnemosyne_memory-1.9.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to Mnemosyne
+
+Mnemosyne is a personal project that grew into something useful. If you're here, you're already part of the community. There are no gatekeepers — bug reports, documentation fixes, feature ideas, and code contributions are all welcome.
+
+## Getting Started
+
+```bash
+git clone https://github.com/AxDSan/mnemosyne.git
+cd mnemosyne
+pip install -e .
+python -m pytest tests/ -v
+```
+
+## What You Can Do
+
+**No contribution is too small.**
+
+- **Report bugs** — Open an issue with steps to reproduce. A clear bug report saves hours.
+- **Improve docs** — Typos, unclear explanations, missing examples. If it confused you, fix it.
+- **Share your use case** — Open a discussion. Real-world usage shapes the roadmap.
+- **Submit code** — See below for guidelines.
+
+## Code Contributions
+
+### Versioning
+
+Mnemosyne uses **Simple Versioning** (`MAJOR.MINOR`, no patch):
+
+- **MINOR** bumps after every iteration: bug fixes, features, docs, refactors.
+- **MAJOR** bumps only for significant new functionality (e.g., 1.0 → 2.0).
+
+`__version__` in `mnemosyne/__init__.py` is the single source of truth. `setup.py` reads from it automatically. If you open a PR that changes user-facing behavior, bump the version and add an entry to `CHANGELOG.md`.
+
+### Principles
+
+Mnemosyne is intentionally minimal. Every addition is weighed against these principles:
+
+- **Local-first:** No cloud dependencies, no required API keys.
+- **Minimal dependencies:** Prefer the Python stdlib. SQLite is the only database.
+- **Zero-config:** Users should not need to edit config files to get basic functionality.
+- **Fast:** Sub-millisecond reads and writes on standard hardware.
+
+### Before You Code
+
+1. **Open an issue first** for non-trivial changes. This prevents wasted effort.
+2. **Keep it focused.** One PR per logical change.
+3. **Add tests.** If you fix a bug or add a feature, include a test in `tests/`.
+4. **Update the README** if user-facing behavior changes.
+5. **Bump the version** in `mnemosyne/__init__.py` and update `CHANGELOG.md`.
+
+### Review Process
+
+There is no formal review board. Pull requests are reviewed by the maintainer and merged when they:
+
+- Pass existing tests
+- Follow the principles above
+- Include a clear description of what changed and why
+
+## Areas of Interest
+
+These are not mandates — just directions where help would be valuable:
+
+- Encrypted backup/sync (optional, user-controlled)
+- Additional embedding model support
+- Multi-language memory processing
+- Better error messages and debugging tools
+
+## Community
+
+- **Issues & bugs:** [GitHub Issues](https://github.com/AxDSan/mnemosyne/issues)
+- **Feature ideas & questions:** [GitHub Discussions](https://github.com/AxDSan/mnemosyne/discussions)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

mnemosyne_memory-1.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdias J
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mnemosyne_memory-1.9.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include CHANGELOG.md
+include LICENSE
+include UPDATING.md
+include CONTRIBUTING.md
+recursive-include docs *.md
+recursive-include assets *
+global-exclude *.pyc
+global-exclude __pycache__
+global-exclude .DS_Store
+global-exclude *.db

mnemosyne_memory-1.9.0/PKG-INFO

@@ -0,0 +1,460 @@
+Metadata-Version: 2.4
+Name: mnemosyne-memory
+Version: 1.9.0
+Summary: The Zero-Dependency, Sub-Millisecond AI Memory System
+Home-page: https://github.com/AxDSan/mnemosyne
+Author: Abdias J
+Author-email: Abdias J <abdi.moya@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/AxDSan/mnemosyne
+Project-URL: Repository, https://github.com/AxDSan/mnemosyne
+Project-URL: Issues, https://github.com/AxDSan/mnemosyne/issues
+Project-URL: Documentation, https://github.com/AxDSan/mnemosyne/blob/main/README.md
+Keywords: ai,memory,sqlite,agent,llm,context,embeddings,vector-store
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: llm
+Requires-Dist: ctransformers>=0.2.27; extra == "llm"
+Requires-Dist: huggingface-hub>=0.20; extra == "llm"
+Provides-Extra: embeddings
+Requires-Dist: fastembed>=0.3.0; extra == "embeddings"
+Provides-Extra: all
+Requires-Dist: ctransformers>=0.2.27; extra == "all"
+Requires-Dist: huggingface-hub>=0.20; extra == "all"
+Requires-Dist: fastembed>=0.3.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Mnemosyne
+
+![Mnemosyne](/assets/mnemosyne.jpg)
+
+> Native, zero-cloud memory for AI agents. SQLite-backed. Sub-millisecond. Fully private.
+
+[![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://python.org)
+[![SQLite](https://img.shields.io/badge/SQLite-3.35+-green.svg)](https://sqlite.org/codeofethics.html)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Mnemosyne is a local-first memory system for the [Hermes Agent](https://github.com/AxDSan/hermes) framework. It stores conversations, preferences, and knowledge in SQLite with native vector search (sqlite-vec) and full-text search (FTS5) — no external databases, no API keys, no network calls.
+
+---
+
+## Quick Start
+
+### Option A: Full install (recommended)
+
+For the CLI, Python API, and Hermes MemoryProvider:
+
+```bash
+# 1. Clone and install
+git clone https://github.com/AxDSan/mnemosyne.git
+cd mnemosyne
+pip install -e .
+```
+
+> ⚠️ **Ubuntu 24.04 / Debian 12 users:** If you get `error: externally-managed-environment`, your system Python is PEP 668-protected. Use a virtual environment:
+> ```bash
+> python3 -m venv .venv
+> source .venv/bin/activate
+> pip install -e .
+> ```
+> Make sure to activate the venv every time you run Hermes, or install Hermes itself inside the same venv.
+
+```bash
+# 2. Register with Hermes
+python -m mnemosyne.install
+
+# 3. Activate as your memory provider
+hermes memory setup
+# → Select "mnemosyne" and press Enter
+```
+
+### Option B: Hermes MemoryProvider only (no pip needed)
+
+If you only need Mnemosyne as a Hermes memory backend and want to skip pip entirely:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/AxDSan/mnemosyne/main/deploy_hermes_provider.sh | bash
+```
+
+This symlinks the provider into `~/.hermes/plugins/mnemosyne` and adds the repo to `sys.path` at runtime. No virtual environment required — works out of the box on Ubuntu 24.04.
+
+Verify:
+
+```bash
+hermes memory status       # Should show "Provider: mnemosyne"
+hermes mnemosyne stats     # Shows working + episodic memory counts
+```
+
+> **Note:** The `hermes memory setup` picker defaults to "Built-in only" every time it opens. This is normal Hermes UI behavior — your previous selection **is** saved. Just select Mnemosyne and press Enter.
+
+---
+
+## What Makes It Different
+
+| | Mnemosyne | Cloud alternatives |
+|---|---|---|
+| **Latency** | < 1ms | 10-100ms |
+| **Dependencies** | Python stdlib + optional ONNX | External APIs, auth, rate limits |
+| **Privacy** | 100% local | Data leaves your machine |
+| **Cost** | Free | Freemium / per-call |
+| **Setup** | `pip install -e .` | API keys, accounts, config |
+
+**Key capabilities:**
+
+- **BEAM architecture** — Three tiers: hot working memory, long-term episodic memory, temporary scratchpad
+- **Hybrid search** — 50% vector similarity + 30% FTS5 rank + 20% importance, all inside SQLite
+- **Automatic consolidation** — Old working memories are summarized and moved to episodic memory via `mnemosyne_sleep()`
+- **Temporal triples** — Time-aware knowledge graph with automatic invalidation
+- **Export / import** — Move your entire memory database to a new machine with one JSON file
+- **Cross-session scope** — `remember(..., scope="global")` makes facts visible everywhere
+- **Configurable compression** — `float32` (default), `int8` (4x smaller), or `bit` (32x smaller) vectors
+
+---
+
+## Benchmarks
+
+All numbers measured on CPU with `sqlite-vec` + FTS5 enabled.
+
+### LongMemEval (ICLR 2025)
+
+| System | Score | Notes |
+|---|---|---|
+| **Mnemosyne (dense)** | **98.9% Recall@All@5** | Oracle subset, 100 instances, bge-small-en-v1.5 |
+| Mempalace | 96.6% Recall@5 | AAAK + Palace architecture |
+| Mastra Observational Memory | 84.23% (gpt-4o) | Three-date model |
+| Full-context GPT-4o baseline | ~60.2% | No memory system |
+
+### Latency vs. Cloud Alternatives
+
+| Operation | Honcho | Zep | MemGPT | **Mnemosyne** | Speedup |
+|---|---|---|---|---|---|
+| **Write** | 45ms | 85ms | 120ms | **0.81ms** | **56x** |
+| **Read** | 38ms | 62ms | 95ms | **0.076ms** | **500x** |
+| **Search** | 52ms | 78ms | 140ms | **1.2ms** | **43x** |
+| **Cold Start** | 500ms | 800ms | 1200ms | **0ms** | **Instant** |
+
+### BEAM Architecture Scaling
+
+**Write throughput:**
+
+| Operation | Count | Total | Avg |
+|---|---|---|---|
+| Working memory writes | 500 | 8.7s | **17.4 ms** |
+| Episodic inserts (with embedding) | 500 | 10.7s | **21.3 ms** |
+| Sleep consolidation | 300 old items | 33 ms | — |
+
+**Hybrid recall scaling (query latency stays flat as corpus grows):**
+
+| Corpus Size | Query | Avg Latency | p95 |
+|---|---|---|---|
+| 100 | "concept 42" | **5.1 ms** | 6.9 ms |
+| 500 | "concept 42" | **5.0 ms** | 5.7 ms |
+| 1,000 | "concept 42" | **5.3 ms** | 6.5 ms |
+| **2,000** | **"concept 42"** | **7.0 ms** | **8.6 ms** |
+
+**Working memory recall scaling (FTS5 fast path):**
+
+| WM Size | Query | Avg Latency | p95 |
+|---|---|---|---|
+| 1,000 | "concept 42" | **2.4 ms** | 3.1 ms |
+| 5,000 | "domain 7" | **3.2 ms** | 3.8 ms |
+| **10,000** | **"concept 42"** | **6.4 ms** | **7.2 ms** |
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Python 3.9+
+- Hermes Agent (for plugin integration)
+
+### Basic
+
+```bash
+git clone https://github.com/AxDSan/mnemosyne.git
+cd mnemosyne
+pip install -e .
+python -m mnemosyne.install
+```
+
+> ⚠️ **Ubuntu 24.04 / Debian 12 users:** If `pip install -e .` fails with `externally-managed-environment`, see the [Quick Start → Option A](#quick-start) note about using a virtual environment.
+
+### Optional dependencies
+
+```bash
+# Dense retrieval (required for semantic search and the 98.9% LongMemEval score)
+pip install fastembed>=0.3.0
+
+# Local LLM consolidation (sleep cycle summarization)
+pip install ctransformers>=0.2.27 huggingface-hub>=0.20
+```
+
+> **Note:** Without `fastembed`, Mnemosyne falls back to keyword-only retrieval. It still works, but you won't get competitive semantic search or the benchmark scores above.
+
+### Uninstall
+
+```bash
+python -m mnemosyne.install --uninstall
+```
+
+### Updating
+
+Mnemosyne is installed from source, so updating is a `git pull` away.
+
+**Option A (pip install -e .):**
+```bash
+cd mnemosyne
+git pull
+# Only re-run pip if setup.py changed (new deps, entry points, CLI commands):
+pip install -e .
+```
+
+**Option B (deploy script / symlink only):**
+```bash
+cd mnemosyne
+git pull
+# Nothing to reinstall — it's a live symlink
+```
+
+**Always restart Hermes** after updating so plugin changes take effect:
+```bash
+hermes gateway restart
+```
+
+**If the update includes database schema changes**, run the migration helper:
+```bash
+python scripts/migrate_from_legacy.py
+```
+
+See [UPDATING.md](UPDATING.md) for detailed troubleshooting and rollback instructions.
+
+---
+
+## Usage
+
+### CLI
+
+```bash
+# Show memory statistics
+hermes mnemosyne stats
+
+# Search memories
+hermes mnemosyne inspect "dark mode preferences"
+
+# Run consolidation (compress old working memory into episodic summaries)
+hermes mnemosyne sleep
+
+# Export all memories to a JSON file
+hermes mnemosyne export --output mnemosyne_backup.json
+
+# Import memories from a JSON file
+hermes mnemosyne import --input mnemosyne_backup.json
+
+# Clear scratchpad
+hermes mnemosyne clear
+```
+
+### Python API
+
+```python
+from mnemosyne import remember, recall
+
+# Store a fact
+remember(
+    content="User prefers dark mode interfaces",
+    importance=0.9,
+    source="preference"
+)
+
+# Store a global preference (visible in every session)
+remember(
+    content="User email is abdi.moya@gmail.com",
+    importance=0.95,
+    source="preference",
+    scope="global"
+)
+
+# Store a temporary credential with expiry
+remember(
+    content="API key: sk-abc123",
+    importance=0.8,
+    source="credential",
+    valid_until="2026-12-31T00:00:00"
+)
+
+# Search memories
+results = recall("interface preferences", top_k=3)
+
+# Temporal knowledge graph
+from mnemosyne.core.triples import TripleStore
+kg = TripleStore()
+kg.add("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")
+kg.query("Maya", as_of="2026-02-01")
+```
+
+### Advanced: BEAM direct access
+
+```python
+from mnemosyne.core.beam import BeamMemory
+
+beam = BeamMemory(session_id="my_session")
+
+# Working memory (auto-injected into prompts)
+beam.remember("Important context", importance=0.9)
+
+# Episodic memory (long-term, searchable)
+beam.consolidate_to_episodic(
+    summary="User likes Neovim",
+    source_wm_ids=["wm1"],
+    importance=0.8
+)
+
+# Scratchpad (temporary reasoning)
+beam.scratchpad_write("todo: fix auth bug")
+
+# Search both tiers
+results = beam.recall("editor preferences", top_k=5)
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    HERMES AGENT                              │
+│                                                              │
+│  ┌─────────────┐     ┌──────────────┐     ┌─────────────┐  │
+│  │   pre_llm   │────▶│  Mnemosyne   │────▶│   SQLite    │  │
+│  │    hook     │     │    BEAM      │     │             │  │
+│  └─────────────┘     └──────────────┘     │ working_mem │  │
+│         ▲                                  │ episodic_mem│  │
+│         │                                  │ vec_episodes│  │
+│         └──────── Auto-injected context ───│ fts_episodes│  │
+│                                            │ scratchpad  │  │
+│                                            │ triples     │  │
+│                                            └─────────────┘  │
+│                                                              │
+│  No HTTP. No cloud. 100% local.                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**BEAM** (Bilevel Episodic-Associative Memory):
+
+- `working_memory` — Hot context, auto-injected before LLM calls, TTL-based eviction
+- `episodic_memory` — Long-term storage with sqlite-vec + FTS5 hybrid search
+- `scratchpad` — Temporary agent reasoning workspace
+
+---
+
+## Why SQLite for Hermes?
+
+SQLite is already in your stack. Hermes uses it for session persistence. Mnemosyne extends that same file — no new dependencies, no Docker containers, no connection pooling.
+
+| Feature | Honcho | Zep | Mnemosyne |
+|---|---|---|---|
+| Deployment | Docker + PostgreSQL | Docker + Postgres | `pip install` |
+| Query Language | REST API | REST API | `SELECT ... WHERE MATCH` |
+| Vector Store | pgvector | pgvector | sqlite-vec |
+| Text Search | Separate API | Separate API | Built-in FTS5 |
+| Auth Required | Yes (supabase) | Yes | No |
+| Offline Mode | No | No | Yes |
+| Cold Start Latency | 500-800ms | 800ms+ | **0ms** |
+
+---
+
+## Backup, Export & Migration
+
+Mnemosyne stores everything in a single SQLite file at `~/.hermes/mnemosyne/data/mnemosyne.db`.
+
+```bash
+# Simple backup
+cp ~/.hermes/mnemosyne/data/mnemosyne.db ~/backups/mnemosyne_$(date +%Y%m%d).db
+
+# Export to JSON (portable across machines)
+hermes mnemosyne export --output mnemosyne_backup.json
+
+# Import on a new machine
+hermes mnemosyne import --input mnemosyne_backup.json
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `MNEMOSYNE_DATA_DIR` | `~/.hermes/mnemosyne/data` | Database directory |
+| `MNEMOSYNE_VEC_TYPE` | `float32` | Vector compression: `float32`, `int8`, or `bit` |
+| `MNEMOSYNE_WM_MAX_ITEMS` | `10000` | Working memory item limit |
+| `MNEMOSYNE_WM_TTL_HOURS` | `24` | Working memory TTL |
+| `MNEMOSYNE_RECENCY_HALFLIFE` | `168` | Recency decay halflife in hours (1 week) |
+
+---
+
+## Testing
+
+```bash
+# Run tests
+python -m pytest tests/test_beam.py -v
+
+# Run benchmarks
+python tests/benchmark_beam_working_memory.py
+```
+
+---
+
+## Contributing
+
+Contributions are welcome. Areas of active interest:
+
+- [ ] Encrypted cloud sync (optional, user-controlled)
+- [ ] Browser extension for web context capture
+- [ ] Additional embedding models
+- [ ] Multi-language support
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT License — See [LICENSE](LICENSE)
+
+Copyright (c) 2026 Abdias J
+
+---
+
+## Acknowledgments
+
+- [Hermes Agent Framework](https://github.com/AxDSan/hermes) — The ecosystem Mnemosyne was built for
+- [Honcho](https://github.com/plasticlabs/honcho) — For defining the stateful memory space
+- [Mempalace](https://github.com/thepersonalaicompany/mempalace) — For proving local-first memory can compete on benchmarks
+- [SQLite](https://sqlite.org/codeofethics.html) — The world's most deployed database
+
+---
+
+<p align="center">
+  <em>"The faintest ink is more powerful than the strongest memory." — Hermes Trismegistus</em>
+</p>