ledgermind 2.7.8__tar.gz

ledgermind-2.7.8/LICENSE

@@ -0,0 +1,198 @@
+📜 LICENSE
+
+Non-Commercial Source Available License (NCSA)
+
+Copyright (c) 2026
+Stanislav Zotov
+All rights reserved.
+
+
+---
+
+1. Definitions
+
+For the purposes of this License:
+
+1.1 “Software”
+
+Means all source code, documentation, configuration files, scripts, schemas, models, and any other materials contained in this repository, including any updates, modifications, or derivative works thereof.
+
+1.2 “Author”
+
+Means Stanislav Zotov, the sole copyright holder of the Software.
+
+1.3 “You”
+
+Means any natural person or legal entity that accesses, uses, copies, modifies, or otherwise interacts with the Software.
+
+1.4 “Commercial Entity”
+
+Means any organization, legal entity, or individual entrepreneur (including sole proprietors / individual entrepreneurs) whose activity is directly or indirectly aimed at economic gain, regardless of whether profit is actually achieved.
+
+Lack of profit, losses, or ineffective management does not change the commercial nature of an entity.
+
+1.5 “Commercial Use”
+
+Means any use of the Software that directly or indirectly participates in, supports, enables, or is part of an activity intended to generate revenue, profit, or economic advantage, whether monetary or non-monetary.
+
+Commercial Use includes, but is not limited to:
+
+use in products or services offered for sale or subscription;
+
+use in internal tools, infrastructure, automation, analytics, or decision-making systems of a Commercial Entity;
+
+use in SaaS, PaaS, hosted, cloud, or managed services;
+
+use in research, development, or prototyping intended for present or future commercial application;
+
+use that reduces costs, increases efficiency, or provides competitive advantage to a Commercial Entity;
+
+use by individual entrepreneurs or self-employed persons.
+
+
+1.6 “Non-Commercial Use”
+
+Means use solely for personal, educational, academic, or experimental purposes, including:
+
+personal pet-projects;
+
+learning, studying, or experimenting with the Software;
+
+academic research;
+
+non-commercial demonstrations.
+
+
+Non-Commercial Use must not be connected to any Commercial Entity or commercial intent.
+
+
+---
+
+2. Grant of Rights (Non-Commercial Only)
+
+Subject to the terms of this License, the Author grants You a limited, non-exclusive, non-transferable, revocable license to:
+
+access and study the source code;
+
+run the Software;
+
+modify the Software;
+
+
+solely for Non-Commercial Use.
+
+
+---
+
+3. Special Permission for Non-Profit Organizations
+
+The following entities are permitted to use the Software without a separate agreement, provided that the use is not connected to any commercial activity:
+
+registered non-profit organizations (NPOs);
+
+universities and educational institutions;
+
+charitable foundations;
+
+academic and research institutions.
+
+
+If such an organization participates in or supports commercial activity, directly or indirectly, this permission is void.
+
+
+---
+
+4. Prohibited Uses
+
+Unless explicitly authorized in writing by the Author, You may not:
+
+1. Use the Software for any Commercial Use.
+
+
+2. Use the Software within or on behalf of any Commercial Entity.
+
+
+3. Integrate the Software into any commercial product, service, or business process.
+
+
+4. Offer the Software or its derivatives as part of paid or revenue-generating activities.
+
+
+5. Use the Software in internal company workflows, even if the Software itself is not sold.
+
+
+6. Redistribute, publish, mirror, or make available the Software or any modified version thereof.
+
+
+7. Create or publish forks of the Software.
+
+
+8. Attempt to bypass or reinterpret the intent of this License.
+
+
+
+
+---
+
+5. Commercial Licensing
+
+Any Commercial Use of the Software is strictly prohibited unless You obtain a separate, explicit, written commercial license agreement from the Author.
+
+The terms of such agreement are defined exclusively by the Author and may include fees, royalties, usage limits, or other conditions.
+
+
+---
+
+6. Contributions and Feedback
+
+Any feedback, suggestions, or code contributions provided to the Author are considered voluntary.
+
+By submitting them, You grant the Author the right to use, modify, incorporate, or discard them without any obligation, compensation, or attribution, unless otherwise agreed in writing.
+
+You do not acquire any ownership or license rights by submitting contributions.
+
+
+---
+
+7. Ownership
+
+The Software is licensed, not sold.
+
+All rights, title, and interest in the Software, including all intellectual property rights, remain exclusively with the Author.
+
+
+---
+
+8. Disclaimer of Warranty
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+
+
+---
+
+9. Limitation of Liability
+
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+
+---
+
+10. Termination
+
+Any violation of this License results in immediate and automatic termination of the granted rights.
+
+Upon termination, You must immediately cease all use of the Software and destroy all copies in Your possession.
+
+
+---
+
+11. Governing Law
+
+This License shall be governed by and construed in accordance with the laws of the Republic of Ecuador, without regard to conflict of law principles.
+
+
+---
+
+12. Final Provisions
+
+This License constitutes the entire agreement between You and the Author concerning the Software and supersedes all prior understandings.

ledgermind-2.7.8/PKG-INFO

@@ -0,0 +1,448 @@
+Metadata-Version: 2.4
+Name: ledgermind
+Version: 2.7.8
+Summary: Monolithic Autonomous Agent Memory Management System
+Author-email: Stanislav Zotov <staszotov555@gmail.com>
+License: 📜 LICENSE
+        
+        Non-Commercial Source Available License (NCSA)
+        
+        Copyright (c) 2026
+        Stanislav Zotov
+        All rights reserved.
+        
+        
+        ---
+        
+        1. Definitions
+        
+        For the purposes of this License:
+        
+        1.1 “Software”
+        
+        Means all source code, documentation, configuration files, scripts, schemas, models, and any other materials contained in this repository, including any updates, modifications, or derivative works thereof.
+        
+        1.2 “Author”
+        
+        Means Stanislav Zotov, the sole copyright holder of the Software.
+        
+        1.3 “You”
+        
+        Means any natural person or legal entity that accesses, uses, copies, modifies, or otherwise interacts with the Software.
+        
+        1.4 “Commercial Entity”
+        
+        Means any organization, legal entity, or individual entrepreneur (including sole proprietors / individual entrepreneurs) whose activity is directly or indirectly aimed at economic gain, regardless of whether profit is actually achieved.
+        
+        Lack of profit, losses, or ineffective management does not change the commercial nature of an entity.
+        
+        1.5 “Commercial Use”
+        
+        Means any use of the Software that directly or indirectly participates in, supports, enables, or is part of an activity intended to generate revenue, profit, or economic advantage, whether monetary or non-monetary.
+        
+        Commercial Use includes, but is not limited to:
+        
+        use in products or services offered for sale or subscription;
+        
+        use in internal tools, infrastructure, automation, analytics, or decision-making systems of a Commercial Entity;
+        
+        use in SaaS, PaaS, hosted, cloud, or managed services;
+        
+        use in research, development, or prototyping intended for present or future commercial application;
+        
+        use that reduces costs, increases efficiency, or provides competitive advantage to a Commercial Entity;
+        
+        use by individual entrepreneurs or self-employed persons.
+        
+        
+        1.6 “Non-Commercial Use”
+        
+        Means use solely for personal, educational, academic, or experimental purposes, including:
+        
+        personal pet-projects;
+        
+        learning, studying, or experimenting with the Software;
+        
+        academic research;
+        
+        non-commercial demonstrations.
+        
+        
+        Non-Commercial Use must not be connected to any Commercial Entity or commercial intent.
+        
+        
+        ---
+        
+        2. Grant of Rights (Non-Commercial Only)
+        
+        Subject to the terms of this License, the Author grants You a limited, non-exclusive, non-transferable, revocable license to:
+        
+        access and study the source code;
+        
+        run the Software;
+        
+        modify the Software;
+        
+        
+        solely for Non-Commercial Use.
+        
+        
+        ---
+        
+        3. Special Permission for Non-Profit Organizations
+        
+        The following entities are permitted to use the Software without a separate agreement, provided that the use is not connected to any commercial activity:
+        
+        registered non-profit organizations (NPOs);
+        
+        universities and educational institutions;
+        
+        charitable foundations;
+        
+        academic and research institutions.
+        
+        
+        If such an organization participates in or supports commercial activity, directly or indirectly, this permission is void.
+        
+        
+        ---
+        
+        4. Prohibited Uses
+        
+        Unless explicitly authorized in writing by the Author, You may not:
+        
+        1. Use the Software for any Commercial Use.
+        
+        
+        2. Use the Software within or on behalf of any Commercial Entity.
+        
+        
+        3. Integrate the Software into any commercial product, service, or business process.
+        
+        
+        4. Offer the Software or its derivatives as part of paid or revenue-generating activities.
+        
+        
+        5. Use the Software in internal company workflows, even if the Software itself is not sold.
+        
+        
+        6. Redistribute, publish, mirror, or make available the Software or any modified version thereof.
+        
+        
+        7. Create or publish forks of the Software.
+        
+        
+        8. Attempt to bypass or reinterpret the intent of this License.
+        
+        
+        
+        
+        ---
+        
+        5. Commercial Licensing
+        
+        Any Commercial Use of the Software is strictly prohibited unless You obtain a separate, explicit, written commercial license agreement from the Author.
+        
+        The terms of such agreement are defined exclusively by the Author and may include fees, royalties, usage limits, or other conditions.
+        
+        
+        ---
+        
+        6. Contributions and Feedback
+        
+        Any feedback, suggestions, or code contributions provided to the Author are considered voluntary.
+        
+        By submitting them, You grant the Author the right to use, modify, incorporate, or discard them without any obligation, compensation, or attribution, unless otherwise agreed in writing.
+        
+        You do not acquire any ownership or license rights by submitting contributions.
+        
+        
+        ---
+        
+        7. Ownership
+        
+        The Software is licensed, not sold.
+        
+        All rights, title, and interest in the Software, including all intellectual property rights, remain exclusively with the Author.
+        
+        
+        ---
+        
+        8. Disclaimer of Warranty
+        
+        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+        
+        
+        ---
+        
+        9. Limitation of Liability
+        
+        IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+        
+        
+        ---
+        
+        10. Termination
+        
+        Any violation of this License results in immediate and automatic termination of the granted rights.
+        
+        Upon termination, You must immediately cease all use of the Software and destroy all copies in Your possession.
+        
+        
+        ---
+        
+        11. Governing Law
+        
+        This License shall be governed by and construed in accordance with the laws of the Republic of Ecuador, without regard to conflict of law principles.
+        
+        
+        ---
+        
+        12. Final Provisions
+        
+        This License constitutes the entire agreement between You and the Author concerning the Software and supersedes all prior understandings.
+        
+Project-URL: Homepage, https://github.com/sl4m3/ledgermind
+Project-URL: Repository, https://github.com/sl4m3/ledgermind
+Project-URL: Bug Tracker, https://github.com/sl4m3/ledgermind/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: pyyaml<7.0.0,>=6.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: nest-asyncio>=1.6.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: mcp>=0.1.0
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.22.0
+Requires-Dist: sse-starlette>=1.6.0
+Requires-Dist: prometheus-client>=0.17.0
+Provides-Extra: vector
+Requires-Dist: annoy>=1.17.0; extra == "vector"
+Requires-Dist: sentence-transformers>=2.2.2; extra == "vector"
+Provides-Extra: gguf
+Requires-Dist: llama-cpp-python>=0.2.0; extra == "gguf"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: ledgermind[gguf,vector]; extra == "all"
+Dynamic: license-file
+
+# LedgerMind
+
+**v2.7.8** · Autonomous Memory Management System for AI Agents
+
+> *LedgerMind is not a memory store — it is a living knowledge core that thinks,
+> heals itself, and evolves without human intervention.*
+
+[![License: NCSA](https://img.shields.io/badge/License-NCSA-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue)](https://python.org)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green)](https://modelcontextprotocol.io)
+
+---
+
+## What is LedgerMind?
+
+Most AI memory systems are passive stores: you write, you read, and if the
+information becomes stale or contradictory — that is your problem. LedgerMind
+takes a fundamentally different approach.
+
+LedgerMind is an **autonomous knowledge lifecycle manager**. It combines a
+hybrid storage engine (SQLite + Git) with a built-in reasoning layer that
+continuously monitors knowledge health, detects conflicts, distills raw
+experience into structured rules, and repairs itself — all in the background,
+without any intervention from the developer or the agent.
+
+### Core Capabilities
+
+| Capability | Description |
+|---|---|
+| **Autonomous Heartbeat** | A background worker runs every 5 minutes: Git sync, reflection, decay, self-healing. |
+| **Intelligent Conflict Resolution** | Vector similarity analysis automatically supersedes outdated decisions (threshold: 70%). |
+| **Multi-agent Namespacing** | Logical partitioning of memory for multiple agents within a single project. |
+| **4-bit GGUF Integration** | Optimized for Termux/Android using Jina v5 Small in 4-bit quantization via Llama-CPP. |
+| **API-Key Authentication** | Secure your MCP and REST endpoints with `X-API-Key` (env: `LEDGERMIND_API_KEY`). |
+| **Real-time Webhooks** | Subscribe external systems to memory events (decisions, proposals, updates). |
+| **Thread-Safe Transactions** | Thread-local transaction isolation and SQLite WAL mode for high concurrency. |
+| **Autonomy Stress Testing** | Built-in test suite for validating Falsifiability, Noise Immunity, and Deep Truth Resolution. |
+| **Canonical Target Registry** | Auto-normalizes target names and resolves aliases to prevent memory fragmentation. |
+| **Autonomous Reflection** | Proposals with confidence ≥ 0.9 are automatically promoted to active decisions. |
+| **Hybrid Storage** | SQLite for fast queries + Git for cryptographic audit and version history. |
+| **MCP Server** | 15 tools with namespacing and pagination support for any compatible client. |
+| **REST Gateway** | FastAPI endpoints + Server-Sent Events + WebSocket for real-time updates. |
+| **Git Evolution** | Automatically generates "Evolving Pattern" proposals based on code changes (minimum 2 commits). |
+
+---
+
+## Architecture at a Glance
+
+```mermaid
+graph TD
+    subgraph Core ["LedgerMind Core"]
+        Bridge["Integration Bridge"]
+        Memory["Memory (Main API)"]
+        Server["MCP / REST Server"]
+        
+        Bridge --> Memory
+        Server <--> Memory
+        
+        subgraph Stores ["Storage Layer"]
+            Semantic["Semantic Store (Git + MD)"]
+            Episodic["Episodic Store (SQLite)"]
+            Vector["Vector Index (NumPy/Jina v5 GGUF)"]
+        end
+        
+        Memory --> Semantic
+        Memory --> Episodic
+        Memory --> Vector
+        
+        subgraph Reasoning ["Reasoning Layer"]
+            Conflict["Conflict Engine"]
+            Reflection["Reflection Engine"]
+            Decay["Decay Engine"]
+            Merge["Merge Engine"]
+            Distillation["Distillation Engine"]
+        end
+        
+        Memory -.-> Reasoning
+    end
+
+    subgraph Background ["Background Process"]
+        Worker["Background Worker (Heartbeat)"]
+        Worker --- WorkerAction["Health Check | Git Sync | Reflection | Decay"]
+        Worker -.-> Webhooks["HTTP Webhooks"]
+    end
+    
+    Worker -.-> Memory
+```
+
+---
+
+## Installation
+
+```bash
+# Basic install
+pip install ledgermind
+
+# With 4-bit vector search (recommended for CPU/Mobile)
+pkg install clang cmake ninja
+pip install llama-cpp-python
+pip install ledgermind[vector]
+```
+
+**Requirements:** Python 3.10+, Git installed and configured in PATH.
+
+---
+
+## Quick Start
+
+### Option A: Library (Direct Integration)
+
+```python
+from ledgermind.core.api.bridge import IntegrationBridge
+
+# Using Jina v5 Small 4-bit GGUF for best accuracy on CPU
+bridge = IntegrationBridge(
+    memory_path="./memory", 
+    vector_model=".ledgermind/models/v5-small-text-matching-Q4_K_M.gguf"
+)
+
+# Inject relevant context into your agent's prompt
+context = bridge.memory.search_decisions("database migrations", namespace="prod_agent")
+
+# Record a structured decision with namespacing
+bridge.memory.record_decision(
+    title="Use Alembic for all database migrations",
+    target="database_migrations",
+    rationale="Alembic provides version-controlled, reversible migrations.",
+    namespace="prod_agent"
+)
+```
+
+### Option B: MCP Server (Secure)
+
+```bash
+# Set your API key for security
+export LEDGERMIND_API_KEY="your-secure-key"
+
+# Start the MCP server
+ledgermind-mcp run --path ./memory
+```
+
+---
+
+## Key Workflows
+
+### Workflow 1: Multi-agent Namespacing — Isolation Within One Core
+
+```python
+# Agent A decision
+memory.record_decision(title="Use PostgreSQL", target="db", namespace="agent_a")
+
+# Agent B decision (same target, different namespace)
+memory.record_decision(title="Use MongoDB", target="db", namespace="agent_b")
+
+# Search only returns what belongs to the agent
+memory.search_decisions("db", namespace="agent_a") # -> Returns PostgreSQL
+```
+
+### Workflow 2: Hybrid Search & Evidence Boost
+
+LedgerMind uses Reciprocal Rank Fusion (RRF) to combine Keyword and Vector
+search. Decisions with more "Evidence Links" (episodic events) receive a
+**+20% boost per link** to their final relevance score.
+
+---
+
+## Documentation
+
+| Document | Description |
+|---|---|
+| [API Reference](docs/API_REFERENCE.md) | Complete reference for all public methods |
+| [Integration Guide](docs/INTEGRATION_GUIDE.md) | Library and MCP integration patterns |
+| [MCP Tools Reference](docs/MCP_TOOLS.md) | All 15 MCP tools with namespacing and offset |
+| [Architecture](docs/ARCHITECTURE.md) | Deep dive into internals and design decisions |
+| [Configuration](docs/CONFIGURATION.md) | API keys, Webhooks, and tuning |
+
+---
+
+## Benchmarks (February 24, 2026, v2.7.8)
+
+LedgerMind (v2.7.8) is optimized for high-speed operation on **Android/Termux**
+as well as containerized environments. It includes built-in security for MCP and
+REST endpoints.
+
+### Retrieval Performance (Jina v5 Small Q4_K_M)
+
+| Metric | Mean (v2.7.8) | Note |
+| :--- | :---: | :--- |
+| **Search p95 (ms)** | **24.2 ms** | Hybrid RRF (Vector + Keyword) |
+| **Write p95 (ms)** | **98.4 ms** | Optimized Metadata Indexing |
+| **Memory OPS** | **15.1 ops/s** | Parallelized write throughput |
+
+---
+
+## License
+
+LedgerMind is distributed under the **Non-Commercial Source Available License
+(NCSA)**.
+
+---
+
+*LedgerMind — the foundation of AI autonomy.*