mnemosynth 0.1.0__tar.gz

mnemosynth-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mnemosynth-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: mnemosynth
+Version: 0.1.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
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: sentence-transformers>=3.0
+Requires-Dist: transformers>=4.40
+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: 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
+```
+
+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 before they corrupt your context
+- **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/
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/vasudevjaiswal/mnemosynth.git
+cd mnemosynth/mnemosynth-core
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+Built by [Vasudev Jaiswal](https://github.com/vasudevjaiswal) · Apache 2.0

mnemosynth-0.1.0/README.md

@@ -0,0 +1,182 @@
+# 🧠 Mnemosynth
+
+**Persistent, hallucination-resistant memory for any LLM, agent, or AI workflow.**
+
+```bash
+pip install mnemosynth
+```
+
+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 before they corrupt your context
+- **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/
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/vasudevjaiswal/mnemosynth.git
+cd mnemosynth/mnemosynth-core
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+Built by [Vasudev Jaiswal](https://github.com/vasudevjaiswal) · Apache 2.0

mnemosynth-0.1.0/pyproject.toml

@@ -0,0 +1,113 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mnemosynth"
+version = "0.1.0"
+description = "Universal AI Memory Plugin — persistent, verified, hallucination-resistant memory for any LLM, agent, or coding workflow"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "Vasudev Jaiswal", email = "vasudevjaiswal@protonmail.com" },
+]
+maintainers = [
+    { name = "Vasudev Jaiswal", email = "vasudevjaiswal@protonmail.com" },
+]
+
+keywords = [
+    "ai", "memory", "mcp", "llm", "knowledge-graph",
+    "vector-db", "cognitive", "agent", "rag", "second-brain",
+    "hallucination", "contradiction-detection", "belief-revision",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "lancedb>=0.15",
+    "pyarrow>=14.0",
+    "networkx>=3.0",
+    "mcp>=1.0",
+    "sentence-transformers>=3.0",
+    "transformers>=4.40",
+    "scikit-learn>=1.4",
+    "click>=8.0",
+    "pyyaml>=6.0",
+    "numpy>=1.24",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "ruff>=0.4",
+    "mypy>=1.10",
+    "pre-commit>=3.0",
+]
+production = [
+    "qdrant-client>=1.9",
+    "falkordb>=1.0",
+    "redis>=5.0",
+]
+
+[project.scripts]
+mnemosynth = "mnemosynth.cli.commands:main"
+
+[project.urls]
+Homepage = "https://github.com/vasudevjaiswal/mnemosynth"
+Repository = "https://github.com/vasudevjaiswal/mnemosynth"
+Documentation = "https://github.com/vasudevjaiswal/mnemosynth#readme"
+Issues = "https://github.com/vasudevjaiswal/mnemosynth/issues"
+Changelog = "https://github.com/vasudevjaiswal/mnemosynth/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mnemosynth"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "TCH"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["mnemosynth"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["src/mnemosynth"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.",
+    "if TYPE_CHECKING:",
+]