AbstractMemory 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

abstractmemory-0.1.0.dist-info/METADATA

@@ -0,0 +1,331 @@
+Metadata-Version: 2.4
+Name: AbstractMemory
+Version: 0.1.0
+Summary: Intelligent memory system for LLM agents with two-tier architecture - temporal knowledge graph memory for sophisticated AI agents
+Author-email: AbstractMemory Team <lpalbou@gmail.com>
+Maintainer-email: AbstractMemory Team <palbou@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lpalbou/AbstractAgent
+Project-URL: Documentation, https://github.com/lpalbou/AbstractAgent#readme
+Project-URL: Repository, https://github.com/lpalbou/AbstractAgent
+Project-URL: Bug Reports, https://github.com/lpalbou/AbstractAgent/issues
+Keywords: llm,memory,stateful,ai,agents,knowledge-graph,temporal,grounded-memory
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: llm
+Requires-Dist: abstractllm>=0.5.0; extra == "llm"
+Provides-Extra: storage
+Requires-Dist: lancedb; extra == "storage"
+Dynamic: license-file
+
+# AbstractMemory
+
+**Intelligent memory system for LLM agents with two-tier architecture**
+
+AbstractMemory provides efficient, purpose-built memory solutions for different types of LLM agents - from simple task-specific tools to sophisticated autonomous agents with persistent, grounded memory.
+
+## 🎯 Project Goals
+
+AbstractMemory is part of the **AbstractLLM ecosystem** refactoring, designed to power both simple and complex AI agents:
+
+- **Simple agents** (ReAct, task tools) get lightweight, efficient memory
+- **Autonomous agents** get sophisticated temporal memory with user tracking
+- **No over-engineering** - memory complexity matches agent purpose
+
+## 🏗️ Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     AbstractLLM Ecosystem                  │
+├─────────────────┬─────────────────┬─────────────────────────┤
+│  AbstractCore   │ AbstractMemory  │    AbstractAgent        │
+│                 │                 │                         │
+│ • LLM Providers │ • Simple Memory │ • ReAct Agents          │
+│ • Sessions      │ • Complex Memory│ • Autonomous Agents     │
+│ • Tools         │ • Temporal KG   │ • Multi-user Agents     │
+└─────────────────┴─────────────────┴─────────────────────────┘
+```
+
+## 🧠 Two-Tier Memory Strategy
+
+### Tier 1: Simple Memory (Task Agents)
+Perfect for focused, single-purpose agents:
+
+```python
+from abstractmemory import create_memory
+
+# ReAct agent memory
+scratchpad = create_memory("scratchpad", max_entries=50)
+scratchpad.add_thought("User wants to learn Python")
+scratchpad.add_action("search", {"query": "Python tutorials"})
+scratchpad.add_observation("Found great tutorials")
+
+# Simple chatbot memory
+buffer = create_memory("buffer", max_messages=100)
+buffer.add_message("user", "Hello!")
+buffer.add_message("assistant", "Hi there!")
+```
+
+### Tier 2: Complex Memory (Autonomous Agents)
+For sophisticated agents with persistence and learning:
+
+```python
+# Autonomous agent with full memory capabilities
+memory = create_memory("grounded", working_capacity=10, enable_kg=True)
+
+# Multi-user context
+memory.set_current_user("alice", relationship="owner")
+memory.add_interaction("I love Python", "Python is excellent!")
+memory.learn_about_user("Python developer")
+
+# Get personalized context
+context = memory.get_full_context("programming", user_id="alice")
+```
+
+## 🔧 Quick Start
+
+### Installation
+
+```bash
+pip install abstractmemory
+
+# For real LLM integration tests
+pip install abstractmemory[llm]
+
+# For LanceDB storage (optional)
+pip install lancedb
+```
+
+### Basic Usage
+
+```python
+from abstractmemory import create_memory
+
+# 1. Choose memory type based on agent purpose
+memory = create_memory("scratchpad")  # Simple task agent
+memory = create_memory("buffer")      # Simple chatbot
+memory = create_memory("grounded")    # Autonomous agent
+
+# 2. Use memory in your agent
+if agent_type == "react":
+    memory.add_thought("Planning the solution...")
+    memory.add_action("execute", {"command": "analyze"})
+    memory.add_observation("Analysis complete")
+
+elif agent_type == "autonomous":
+    memory.set_current_user("user123")
+    memory.add_interaction(user_input, agent_response)
+    context = memory.get_full_context(query)
+```
+
+### 🗂️ Persistent Storage Options
+
+AbstractMemory now supports sophisticated storage for observable, searchable AI memory:
+
+#### Observable Markdown Storage
+Perfect for development, debugging, and transparency:
+
+```python
+# Human-readable, version-controllable AI memory
+memory = create_memory(
+    "grounded",
+    storage_backend="markdown",
+    storage_path="./memory"
+)
+
+# Generates organized structure:
+# memory/
+# ├── verbatim/alice/2025/09/24/10-30-45_python_int_abc123.md
+# ├── experiential/2025/09/24/10-31-02_learning_note_def456.md
+# ├── links/2025/09/24/int_abc123_to_note_def456.json
+# └── index.json
+```
+
+#### Powerful Vector Search
+High-performance search with AbstractCore embeddings:
+
+```python
+from abstractllm import create_llm
+
+# Create provider with embedding support
+provider = create_llm("openai", embedding_model="text-embedding-3-small")
+
+# Vector search storage
+memory = create_memory(
+    "grounded",
+    storage_backend="lancedb",
+    storage_uri="./memory.db",
+    embedding_provider=provider
+)
+
+# Semantic search across stored interactions
+results = memory.search_stored_interactions("machine learning concepts")
+```
+
+#### Dual Storage - Best of Both Worlds
+Complete observability with powerful search:
+
+```python
+# Dual storage: markdown (observable) + LanceDB (searchable)
+memory = create_memory(
+    "grounded",
+    storage_backend="dual",
+    storage_path="./memory",
+    storage_uri="./memory.db",
+    embedding_provider=provider
+)
+
+# Every interaction stored in both formats
+# - Markdown files for complete transparency
+# - Vector database for semantic search
+```
+
+## 📚 Documentation
+
+- **[Architecture Guide](docs/architecture.md)** - Complete system design
+- **[Memory Types](docs/memory-types.md)** - Detailed component guide
+- **[Storage Systems](docs/storage-systems.md)** - Persistent storage with dual backends
+- **[Usage Patterns](docs/usage-patterns.md)** - Real-world examples
+- **[API Reference](docs/api-reference.md)** - Complete API documentation
+- **[Integration Guide](docs/integration.md)** - AbstractLLM ecosystem integration
+- **[AbstractCore Embedding Specs](docs/abstractcore-embedding-specs.md)** - Embedding integration requirements
+
+## 🔬 Key Features
+
+### ✅ Purpose-Built Memory Types
+- **ScratchpadMemory**: ReAct thought-action-observation cycles
+- **BufferMemory**: Simple conversation history
+- **GroundedMemory**: Multi-dimensional temporal memory
+
+### ✅ State-of-the-Art Research Integration
+- **MemGPT/Letta Pattern**: Self-editing core memory
+- **Temporal Grounding**: WHO (relational) + WHEN (temporal) context
+- **Zep/Graphiti Architecture**: Bi-temporal knowledge graphs
+
+### ✅ Four-Tier Memory Architecture (Autonomous Agents)
+```
+Core Memory ──→ Semantic Memory ──→ Working Memory ──→ Episodic Memory
+   (Identity)     (Validated Facts)    (Recent Context)   (Event Archive)
+```
+
+### ✅ Learning Capabilities
+- **Failure/Success Tracking**: Learn from experience
+- **User Personalization**: Multi-user context separation
+- **Fact Validation**: Confidence-based knowledge consolidation
+
+### ✅ Dual Storage Architecture
+- **📄 Markdown Storage**: Human-readable, observable AI memory evolution
+- **🔍 LanceDB Storage**: Vector search with SQL capabilities via AbstractCore
+- **🔄 Dual Mode**: Best of both worlds - transparency + powerful search
+- **🧠 AI Reflections**: Automatic experiential notes about interactions
+- **🔗 Bidirectional Links**: Connect interactions to AI insights
+- **📊 Search Capabilities**: Text-based and semantic similarity search
+
+## 🧪 Testing & Validation
+
+AbstractMemory includes **200+ comprehensive tests** with real implementations:
+
+```bash
+# Run all tests
+python -m pytest tests/ -v
+
+# Run specific test suites
+python -m pytest tests/simple/ -v          # Simple memory types
+python -m pytest tests/components/ -v      # Memory components
+python -m pytest tests/storage/ -v         # Storage system tests
+python -m pytest tests/integration/ -v     # Full system integration
+
+# Test with real LLM providers (requires AbstractCore)
+python -m pytest tests/integration/test_llm_real_usage.py -v
+
+# Test comprehensive dual storage serialization
+python -m pytest tests/storage/test_dual_storage_comprehensive.py -v
+```
+
+## 🔗 AbstractLLM Ecosystem Integration
+
+AbstractMemory seamlessly integrates with the broader ecosystem:
+
+### With AbstractCore
+```python
+from abstractllm import create_llm
+from abstractmemory import create_memory
+
+# Create LLM provider
+provider = create_llm("anthropic", model="claude-3-5-haiku-latest")
+
+# Create memory with embedding integration
+memory = create_memory(
+    "grounded",
+    enable_kg=True,
+    storage_backend="dual",
+    storage_path="./memory",
+    storage_uri="./memory.db",
+    embedding_provider=provider
+)
+
+# Use together in agent reasoning
+context = memory.get_full_context(query)
+response = provider.generate(prompt, system_prompt=context)
+memory.add_interaction(query, response.content)
+
+# Search stored memories with semantic similarity
+similar_memories = memory.search_stored_interactions("related concepts")
+```
+
+### With AbstractAgent (Future)
+```python
+from abstractagent import create_agent
+from abstractmemory import create_memory
+
+# Autonomous agent with sophisticated memory
+memory = create_memory("grounded", working_capacity=20)
+agent = create_agent("autonomous", memory=memory, provider=provider)
+
+# Agent automatically uses memory for consistency and personalization
+response = agent.execute(task, user_id="alice")
+```
+
+## 🏛️ Architecture Principles
+
+1. **No Over-Engineering**: Memory complexity matches agent requirements
+2. **Real Implementation Testing**: No mocks - all tests use real implementations
+3. **SOTA Research Foundation**: Built on proven patterns (MemGPT, Zep, Graphiti)
+4. **Clean Abstractions**: Simple interfaces, powerful implementations
+5. **Performance Optimized**: Fast operations for simple agents, scalable for complex ones
+
+## 📈 Performance Characteristics
+
+- **Simple Memory**: < 1ms operations, minimal overhead
+- **Complex Memory**: < 100ms context generation, efficient consolidation
+- **Scalability**: Handles thousands of memory items efficiently
+- **Real LLM Integration**: Context + LLM calls complete in seconds
+
+## 🤝 Contributing
+
+AbstractMemory is part of the AbstractLLM ecosystem. See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
+
+## 📄 License
+
+[License details]
+
+---
+
+**AbstractMemory: Smart memory for smart agents** 🧠✨

abstractmemory-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+abstractmemory/__init__.py,sha256=kCU1QIwh4MudeRTiti4KoPP3ZyoBAo2mjHdAAjpZZHA,32391
+abstractmemory/simple.py,sha256=mZmz7JX0zkzgvWVfC8xrpqCK1Zx43lyr4MBGWD8OQqM,4969
+abstractmemory/cognitive/__init__.py,sha256=6L9dF3Y_OdRct7o8Hn04d4UvzlRyevNh0Etxs6CwLME,40
+abstractmemory/components/__init__.py,sha256=mTMDpRZRaVz6HPQ9C-xvNccFD0xurfVeDP-mCZ5b3SQ,46
+abstractmemory/components/core.py,sha256=RRAKhnnxsvqKpSkAJwu5mU44_B7Sl_2KTE448H_AMZs,4307
+abstractmemory/components/episodic.py,sha256=Uq4VUu27vOip5hxBq7PspmskMhxmSHiGg3iEG_5lypc,2357
+abstractmemory/components/semantic.py,sha256=tukZtR1-VCH07-6D6nPXyZ9H-6Ko3jE4NQhOeqLUeQc,4043
+abstractmemory/components/working.py,sha256=4U11V8ZZzKgLs4EdcsCRTKmctQ64k9xk69_0ytFQbYA,1570
+abstractmemory/core/__init__.py,sha256=djQvbM76uRfL4ugZgu7gW-ZEKK1wcqm0nVPXgqGq_JA,44
+abstractmemory/core/interfaces.py,sha256=4hvoeHumBCCCyEmvmt46pFSegXHnd0c4UUN0Fp0CFi0,2757
+abstractmemory/core/temporal.py,sha256=4BR_cAJBpX7rlFnYEN4jcdhaOLkUWaCzAYI9aPX6K0M,3526
+abstractmemory/graph/__init__.py,sha256=hW927TXsGYJDc3qN4r2zrXiMl7lEk1d81h1siov1GgE,41
+abstractmemory/graph/knowledge_graph.py,sha256=PWWBhsj2Nv4BesVGS_FjBwu88cVi1iNEHjlBRhirMlw,6805
+abstractmemory/storage/__init__.py,sha256=GLvuzeukQ2o84AkN0yH6rB4vhLgMXsd-6up9Mw6icoE,340
+abstractmemory/storage/dual_manager.py,sha256=3RUBqeIm_fa_Tqqv8ymPMBJKEzWj29AeuG8TBD15M0M,11724
+abstractmemory/storage/lancedb_storage.py,sha256=Wp928f-HWVJ4lnBi7XY_loCM5HXD9QVGWwrx2odAgVk,15578
+abstractmemory/storage/markdown_storage.py,sha256=h5EVxPrEnYw-X3AhB_8DyfiEc944MywgEDv2e6LcNZA,16054
+abstractmemory-0.1.0.dist-info/licenses/LICENSE,sha256=NKLs197QnnfbXxdwIttTjZb1IHcj5IUTD-qXnr_V8Fw,1082
+abstractmemory-0.1.0.dist-info/METADATA,sha256=4hndUIsA9OvJBlfQRNgYZcHJ3LtM1vqczpDWyDl9e3M,11956
+abstractmemory-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+abstractmemory-0.1.0.dist-info/top_level.txt,sha256=ALpTfrLlzRBy55aam5M8YuOi-4i_shfsq1DcgTR6_NQ,15
+abstractmemory-0.1.0.dist-info/RECORD,,

{abstractmemory-0.0.1.dist-info → abstractmemory-0.1.0.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 AbstractMemory Team
+Copyright (c) 2025 Laurent-Philippe Albou
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +19,6 @@ 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.
+
+
+

abstractmemory-0.0.1.dist-info/METADATA

@@ -1,94 +0,0 @@
-Metadata-Version: 2.4
-Name: AbstractMemory
-Version: 0.0.1
-Summary: PLACEHOLDER: Memory system for transforming stateless LLMs into stateful LLMs - primarily designed for AbstractLLM integration
-Author-email: AbstractMemory Team <contact@example.com>
-Maintainer-email: AbstractMemory Team <contact@example.com>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/abstractmemory/abstractmemory
-Project-URL: Documentation, https://github.com/abstractmemory/abstractmemory#readme
-Project-URL: Repository, https://github.com/abstractmemory/abstractmemory
-Project-URL: Bug Reports, https://github.com/abstractmemory/abstractmemory/issues
-Keywords: llm,memory,stateful,ai,placeholder
-Classifier: Development Status :: 1 - Planning
-Classifier: Intended Audience :: Developers
-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: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# AbstractMemory - PLACEHOLDER PROJECT
-
-⚠️ **WARNING: This is a placeholder package** ⚠️
-
-## Overview
-
-AbstractMemory is a placeholder package that reserves the name on PyPI for a future memory system designed to transform stateless LLMs into stateful LLMs.
-
-## Current Status
-
-**This package is currently a PLACEHOLDER and should NOT be used in production.**
-
-The actual memory system implementation is currently integrated within the AbstractLLM project. This separate package exists to:
-
-1. **Reserve the PyPI name** for future modularization
-2. **Enable clean separation of concerns** when the code is extracted from AbstractLLM
-3. **Facilitate better evolution and maintenance** of the memory system as a standalone component
-4. **Allow reusability** across different LLM frameworks in the future
-
-## Future Vision
-
-AbstractMemory will provide:
-
-- **Stateful Memory Management**: Transform stateless LLMs into stateful systems
-- **Primary AbstractLLM Integration**: Seamless integration with AbstractLLM
-- **Modular Architecture**: Clean separation from core LLM functionality
-- **Extensible Framework**: Support for various memory strategies and backends
-
-## Installation
-
-```bash
-pip install AbstractMemory
-```
-
-## Usage
-
-Currently, attempting to use any functionality will raise a `PlaceholderError`:
-
-```python
-import abstractmemory
-
-# This will raise PlaceholderError
-abstractmemory.placeholder_warning()
-```
-
-## Development Timeline
-
-The actual implementation will be extracted and modularized from AbstractLLM when:
-- The AbstractLLM memory system reaches sufficient maturity
-- Clean interfaces are established
-- Comprehensive testing framework is in place
-
-## Contributing
-
-This is a placeholder project. For memory-related contributions, please refer to the AbstractLLM project until the code is modularized.
-
-## License
-
-MIT License - See LICENSE file for details.
-
-## Contact
-
-For questions about future development plans, please refer to the AbstractLLM project documentation.
-
----
-
-**Remember: This is a placeholder. The real implementation is coming soon!**

abstractmemory-0.0.1.dist-info/RECORD

@@ -1,6 +0,0 @@
-abstractmemory/__init__.py,sha256=56ZUm3WI5FFZRBoPwwAC4Zj0lK1vglE7RTj3a6yAFFY,1362
-abstractmemory-0.0.1.dist-info/licenses/LICENSE,sha256=lPn7wpbMAgGyv2OAhgHtW_bZHq4Hnm7Gx28-8m82Nt4,1076
-abstractmemory-0.0.1.dist-info/METADATA,sha256=2kDPyAPoE1e7XGR0_zvRWYp2FmbkHDJRN3vqv17m2XA,3420
-abstractmemory-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-abstractmemory-0.0.1.dist-info/top_level.txt,sha256=ALpTfrLlzRBy55aam5M8YuOi-4i_shfsq1DcgTR6_NQ,15
-abstractmemory-0.0.1.dist-info/RECORD,,