alma-memory 0.5.0__tar.gz → 0.7.0__tar.gz

{alma_memory-0.5.0 → alma_memory-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alma-memory
-Version: 0.5.0
+Version: 0.7.0
 Summary: Agent Learning Memory Architecture - Persistent memory for AI agents
 Author-email: RBKunnela <aiagentsprompt@gmail.com>
 License: MIT
@@ -41,6 +41,10 @@ Requires-Dist: pinecone>=3.0.0; extra == "pinecone"
 Provides-Extra: mcp
 Requires-Dist: pydantic>=2.0.0; extra == "mcp"
 Requires-Dist: aiohttp>=3.9.0; extra == "mcp"
+Provides-Extra: observability
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "observability"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "observability"
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == "observability"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -52,17 +56,70 @@ Requires-Dist: black>=24.0.0; extra == "dev"
 Requires-Dist: bandit[toml]>=1.7.0; extra == "dev"
 Requires-Dist: numpy>=1.24.0; extra == "dev"
 Provides-Extra: all
-Requires-Dist: alma-memory[azure,chroma,dev,local,mcp,pinecone,postgres,qdrant]; extra == "all"
+Requires-Dist: alma-memory[azure,chroma,dev,local,mcp,observability,pinecone,postgres,qdrant]; extra == "all"
 
 # ALMA - Agent Learning Memory Architecture
 
 [![PyPI version](https://badge.fury.io/py/alma-memory.svg)](https://pypi.org/project/alma-memory/)
+[![npm version](https://img.shields.io/badge/npm-v0.6.0-cb3837?logo=npm)](https://github.com/RBKunnela/ALMA-memory/pkgs/npm/alma-memory)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/RBKunnela/ALMA-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/RBKunnela/ALMA-memory/actions/workflows/ci.yml)
-[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Documentation](https://img.shields.io/badge/docs-alma--memory.pages.dev-blue)](https://alma-memory.pages.dev)
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow?logo=buy-me-a-coffee)](https://buymeacoffee.com/aiagentsprp)
 
-> Persistent memory for AI agents that learn and improve over time - without model weight updates.
+<div align="center">
+
+### 🧠 AI Agents That Actually Learn
+
+**Persistent memory for AI agents that improves over time - no fine-tuning required.**
+
+[**🌐 Visit alma-memory.pages.dev →**](https://alma-memory.pages.dev)
+
+</div>
+
+---
+
+**[📖 Documentation](https://alma-memory.pages.dev)** · **[🔧 Technical Reference](docs/TECHNICAL.md)** · **[📦 PyPI](https://pypi.org/project/alma-memory/)** · **[📦 npm](https://github.com/RBKunnela/ALMA-memory/pkgs/npm/alma-memory)** · **[☕ Support](https://buymeacoffee.com/aiagentsprp)**
+
+---
+
+## Looking for a Mem0 Alternative? LangChain Memory Replacement?
+
+**ALMA is the answer.** If you've tried Mem0 or LangChain Memory and found them lacking for production AI agents, ALMA was built specifically to solve those gaps:
+
+| If you need... | Mem0 | LangChain | **ALMA** |
+|----------------|------|-----------|----------|
+| Scoped learning (agents only learn their domain) | ❌ | ❌ | ✅ |
+| Anti-pattern tracking (what NOT to do) | ❌ | ❌ | ✅ |
+| Multi-agent knowledge sharing | ❌ | ❌ | ✅ |
+| TypeScript/JavaScript SDK | ❌ | ✅ | ✅ |
+| MCP integration (Claude Code) | ❌ | ❌ | ✅ |
+| 6 vector database backends | Limited | Limited | ✅ |
+| Graph memory for relationships | Limited | Limited | ✅ |
+| Workflow checkpoints & state merging | ❌ | ❌ | ✅ |
+
+**See detailed comparisons:** [ALMA vs Mem0](https://alma-memory.pages.dev/comparison/mem0-vs-alma.html) · [ALMA vs LangChain Memory](https://alma-memory.pages.dev/comparison/langchain-memory-vs-alma.html)
+
+---
+
+## The Problem I Solved
+
+I was building AI agents for automated testing. Helena for frontend QA, Victor for backend verification. They worked great... until they didn't.
+
+**The same mistakes kept happening:**
+
+- Helena would use `sleep(5000)` for waits, causing flaky tests
+- Victor would forget that the API uses JWT with 24-hour expiry
+- Both agents would repeat failed strategies session after session
+
+Every conversation started fresh. No memory. No learning. Just an expensive LLM making the same mistakes I'd already corrected.
+
+I tried **Mem0**. It stores memories, but no way to scope what an agent can learn, no anti-pattern tracking, no multi-agent sharing. I looked at **LangChain Memory**. It's for conversation context, not long-term learning.
+
+**Nothing fit. So I built ALMA.**
+
+The core insight: AI agents don't need to modify their weights to "learn." They need **smart prompts** built from **relevant past experiences.**
 
 ---
 
@@ -79,7 +136,7 @@ ALMA isn't just another memory framework. Here's what sets it apart from alterna
 | **Event System** | Webhooks + in-process callbacks | None | React to memory changes in real-time |
 | **TypeScript SDK** | Full-featured client library | None | First-class JavaScript/TypeScript support |
 | **Vector DB Support** | 6 backends (PostgreSQL, Qdrant, Pinecone, Chroma, SQLite, Azure) | Limited | Deploy anywhere |
-| **Graph Memory** | Pluggable backends (Neo4j, In-memory) | Limited | Entity relationship tracking |
+| **Graph Memory** | Pluggable backends (Neo4j, Memgraph, Kuzu, In-memory) | Limited | Entity relationship tracking |
 | **Harness Pattern** | Decouples agent from domain memory | None | Reusable agent architecture |
 | **MCP Integration** | Native stdio/HTTP server | None | Direct Claude Code integration |
 | **Domain Memory Factory** | 6 pre-built schemas | None | Instant setup for any domain |
@@ -87,58 +144,81 @@ ALMA isn't just another memory framework. Here's what sets it apart from alterna
 
 **Bottom line:** ALMA is purpose-built for AI agents that need to learn, remember, and improve - not just store and retrieve.
 
+### Quick Comparison: ALMA vs Mem0 vs Graphiti
+
+| Feature | ALMA | Mem0 | Graphiti |
+|---------|------|------|----------|
+| Memory Scoping | ✅ `can_learn`/`cannot_learn` | ❌ | ❌ |
+| Anti-Pattern Learning | ✅ `why_bad` + `better_alternative` | ❌ | ❌ |
+| Multi-Agent Inheritance | ✅ `inherit_from`/`share_with` | ❌ | ❌ |
+| Multi-Factor Scoring | ✅ 4 factors (similarity + recency + success + confidence) | ❌ similarity only | ❌ similarity only |
+| MCP Integration | ✅ 16 tools | ❌ | ❌ |
+| Workflow Checkpoints | ✅ | ❌ | ❌ |
+| TypeScript SDK | ✅ | ❌ | ❌ |
+| Graph + Vector Hybrid | ✅ | Limited | ✅ |
+
+**The key insight:** Most solutions treat memory as "store embeddings, retrieve similar." ALMA treats it as "teach agents to improve within safe boundaries."
+
 ---
 
-## What's New in v0.5.0
-
-### Phase 2: Vector Database Backends
-
-- **Qdrant Backend** (`alma/storage/qdrant.py`)
-  - Full StorageBackend implementation with vector similarity search
-  - Metadata filtering for all queries
-  - Optimized `MatchAny` queries for multi-agent memory sharing
-
-- **Pinecone Backend** (`alma/storage/pinecone.py`)
-  - Namespace-based organization per memory type
-  - Serverless spec support for automatic scaling
-  - Environment variable expansion in configuration
-
-- **Chroma Backend** (`alma/storage/chroma.py`)
-  - Persistent, client-server, and ephemeral modes
-  - Native embedding storage and similarity search
-  - Lightweight local development option
-
-- **Graph Database Abstraction** (`alma/graph/`)
-  - Pluggable `GraphBackend` interface
-  - Neo4j backend for production
-  - In-memory backend for testing
-  - Factory function `create_graph_backend()` for easy setup
-
-### Phase 1: Core Features
-
-- **Memory Consolidation Engine** (`alma/consolidation/`)
-  - LLM-powered deduplication that merges similar memories
-  - Cosine similarity-based grouping with configurable thresholds
-  - Provenance tracking (merged_from metadata)
-  - Dry-run mode for safety
-
-- **Event System** (`alma/events/`)
-  - In-process callbacks via `EventEmitter`
-  - Webhook delivery with HMAC signatures
-  - Event types: CREATED, UPDATED, DELETED, ACCESSED, CONSOLIDATED
-  - Retry logic with exponential backoff
-
-- **TypeScript/JavaScript SDK** (`packages/alma-memory-js/`)
-  - Full API coverage: retrieve, learn, addPreference, addKnowledge, forget
-  - Type-safe with comprehensive TypeScript definitions
-  - Error hierarchy matching Python SDK
-  - Automatic retry with configurable backoff
-
-- **Multi-Agent Memory Sharing**
-  - `inherit_from`: Read memories from other agents
-  - `share_with`: Make your memories readable by others
-  - Origin tracking via `metadata['shared_from']`
-  - Optimized batch queries across agents
+## What's New in v0.6.0
+
+### Workflow Context Layer
+
+The major theme of v0.6.0 is **multi-agent workflow support** - enabling agents to coordinate across long-running tasks with checkpoints, state merging, and artifact tracking.
+
+- **Checkpoint & Resume** (`alma/workflow/`)
+  - Save workflow state at any point: `alma.checkpoint(workflow_id, state, metadata)`
+  - Resume from checkpoints after failures or handoffs: `alma.resume(workflow_id)`
+  - Automatic cleanup of old checkpoints: `alma.cleanup_checkpoints(older_than_days=7)`
+
+- **State Reducers for Multi-Agent Workflows**
+  - Merge states from parallel agents: `alma.merge_states(workflow_id, states, reducer)`
+  - Built-in reducers: `latest_wins`, `merge_lists`, `priority_agent`
+  - Custom reducer functions for complex merge logic
+
+- **Artifact Linking**
+  - Link outputs to workflows: `alma.link_artifact(workflow_id, artifact_type, ref)`
+  - Artifact types: `code`, `test`, `document`, `config`, `deployment`
+  - Retrieve all artifacts: `alma.get_artifacts(workflow_id)`
+
+- **Scoped Retrieval**
+  - Filter memories by workflow context: `alma.retrieve_scoped(query, scope)`
+  - Scopes: `workflow_only`, `agent_only`, `project_wide`
+
+- **Session Persistence**
+  - Session handoffs now persist to storage backend
+  - Lazy loading for performance
+  - Survives process restarts
+
+- **MCP Workflow Tools** (8 new tools)
+  - `alma_consolidate`, `alma_checkpoint`, `alma_resume`
+  - `alma_merge_states`, `alma_workflow_learn`
+  - `alma_link_artifact`, `alma_get_artifacts`
+  - `alma_cleanup_checkpoints`, `alma_retrieve_scoped`
+
+- **TypeScript SDK v0.6.0** (`packages/alma-memory-js/`)
+  - Full workflow API parity with Python SDK
+  - 9 new methods: `consolidate()`, `checkpoint()`, `resume()`, `mergeStates()`, `workflowLearn()`, `linkArtifact()`, `getArtifacts()`, `cleanupCheckpoints()`, `retrieveScoped()`
+  - 25+ new TypeScript types for workflow context
+  - Published to GitHub Packages: `@rbkunnela/alma-memory`
+
+### Previous Releases
+
+<details>
+<summary>v0.5.0 - Vector Database Backends</summary>
+
+- **Qdrant Backend** - Full vector similarity search with metadata filtering
+- **Pinecone Backend** - Serverless spec support, namespace organization
+- **Chroma Backend** - Persistent, client-server, and ephemeral modes
+- **Graph Database Abstraction** - Neo4j, Memgraph, Kuzu, In-memory backends
+- **Testing Module** - MockStorage, MockEmbedder, factory functions
+- **Memory Consolidation Engine** - LLM-powered deduplication
+- **Event System** - Webhooks + in-process callbacks
+- **TypeScript SDK** - Initial release with core API
+- **Multi-Agent Memory Sharing** - inherit_from, share_with
+
+</details>
 
 See [CHANGELOG.md](CHANGELOG.md) for the complete history.
 
@@ -194,11 +274,15 @@ pip install alma-memory[azure]     # Azure Cosmos DB + Azure OpenAI
 pip install alma-memory[all]
 ```
 
-**TypeScript/JavaScript:**
+**TypeScript/JavaScript (via GitHub Packages):**
 ```bash
-npm install alma-memory
+# Configure npm for the scope (one-time)
+echo "@rbkunnela:registry=https://npm.pkg.github.com" >> ~/.npmrc
+
+# Install
+npm install @rbkunnela/alma-memory
 # or
-yarn add alma-memory
+yarn add @rbkunnela/alma-memory
 ```
 
 ---
@@ -241,7 +325,7 @@ alma.learn(
 ### TypeScript/JavaScript
 
 ```typescript
-import { ALMA } from 'alma-memory';
+import { ALMA } from '@rbkunnela/alma-memory';
 
 // Create client
 const alma = new ALMA({
@@ -434,14 +518,23 @@ Capture entity relationships for complex reasoning:
 ```python
 from alma.graph import create_graph_backend, BackendGraphStore, EntityExtractor
 
-# Create graph backend (Neo4j for production, memory for testing)
+# Create graph backend - multiple options available:
+
+# Neo4j (production, hosted)
 backend = create_graph_backend(
     "neo4j",
     uri="neo4j+s://xxx.databases.neo4j.io",
     username="neo4j",
     password="your-password"
 )
-# Or for testing:
+
+# Memgraph (high-performance, in-memory)
+# backend = create_graph_backend("memgraph", uri="bolt://localhost:7687")
+
+# Kuzu (embedded, no server required)
+# backend = create_graph_backend("kuzu", database_path="./my_graph_db")
+
+# In-memory (testing)
 # backend = create_graph_backend("memory")
 
 # Create store with backend
@@ -516,9 +609,10 @@ python -m alma.mcp --config .alma/config.yaml
 }
 ```
 
-**Available MCP Tools:**
-| Tool | Description |
-|------|-------------|
+**Available MCP Tools (16 total):**
+
+| Core Tools | Description |
+|------------|-------------|
 | `alma_retrieve` | Get memories for a task |
 | `alma_learn` | Record task outcome |
 | `alma_add_preference` | Add user preference |
@@ -527,6 +621,18 @@ python -m alma.mcp --config .alma/config.yaml
 | `alma_stats` | Get memory statistics |
 | `alma_health` | Health check |
 
+| Workflow Tools (v0.6.0) | Description |
+|-------------------------|-------------|
+| `alma_consolidate` | Merge similar memories |
+| `alma_checkpoint` | Save workflow state |
+| `alma_resume` | Resume from checkpoint |
+| `alma_merge_states` | Merge parallel agent states |
+| `alma_workflow_learn` | Learn with workflow context |
+| `alma_link_artifact` | Link output to workflow |
+| `alma_get_artifacts` | Get workflow artifacts |
+| `alma_cleanup_checkpoints` | Clean old checkpoints |
+| `alma_retrieve_scoped` | Scoped memory retrieval |
+
 ---
 
 ## Advanced Features
@@ -657,7 +763,7 @@ print(f"Recommendation: {signal.recommendation}")
 
 ```
 +-------------------------------------------------------------------------+
-|                          ALMA v0.5.0                                    |
+|                          ALMA v0.6.0                                    |
 +-------------------------------------------------------------------------+
 |  HARNESS LAYER                                                          |
 |  +-----------+  +-----------+  +-----------+  +----------------+        |
@@ -693,9 +799,12 @@ print(f"Recommendation: {signal.recommendation}")
 |  +---------------+  +------------------+  +---------------+             |
 +-------------------------------------------------------------------------+
 |  GRAPH LAYER                                                            |
-|  +---------------+  +------------------+                                |
-|  |    Neo4j      |  |   In-Memory      |                                |
-|  +---------------+  +------------------+                                |
+|  +---------------+  +------------------+  +---------------+             |
+|  |    Neo4j      |  |    Memgraph      |  |     Kuzu      |             |
+|  +---------------+  +------------------+  +---------------+             |
+|  +---------------+                                                      |
+|  |   In-Memory   |                                                      |
+|  +---------------+                                                      |
 +-------------------------------------------------------------------------+
 |  INTEGRATION LAYER                                                      |
 |  +-------------------------------------------------------------------+  |
@@ -819,6 +928,12 @@ chroma:
 | Pinecone Backend | Serverless vector DB | Done |
 | Chroma Backend | Lightweight vector DB | Done |
 | Graph Abstraction | Pluggable graph backends | Done |
+| Testing Module | Mocks and factories for testing | Done |
+| Workflow Context | Checkpoints, state merging, artifacts | Done |
+| Session Persistence | Persistent session handoffs | Done |
+| Scoped Retrieval | Filter by workflow/agent/project | Done |
+| MCP Workflow Tools | 8 additional MCP tools | Done |
+| TypeScript SDK v0.6.0 | Full workflow API support | Done |
 
 ---
 
@@ -850,6 +965,16 @@ docker run -p 6333:6333 qdrant/qdrant
 - Ensure `embedding_dim` in config matches your embedding provider
 - Local: 384, Azure text-embedding-3-small: 1536
 
+**Memgraph connection refused**
+```bash
+# Start Memgraph with Docker
+docker run -p 7687:7687 memgraph/memgraph-mage
+```
+
+**Kuzu database locked**
+- Ensure only one process accesses the database at a time
+- Use `read_only=True` for concurrent read access
+
 ### Debug Logging
 
 ```python
@@ -873,11 +998,18 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## Roadmap
 
-**Completed:**
+**Completed (v0.6.0):**
+- Workflow context layer (checkpoints, state merging, artifacts)
+- Session persistence
+- Scoped retrieval
+- MCP workflow tools (8 new tools)
+- TypeScript SDK v0.6.0 with full workflow support
+
+**Completed (v0.5.0):**
 - Multi-agent memory sharing
 - Memory consolidation engine
 - Event system / webhooks
-- TypeScript SDK
+- TypeScript SDK (initial)
 - Qdrant, Pinecone, Chroma backends
 - Graph database abstraction
 
@@ -896,10 +1028,50 @@ MIT
 
 ---
 
-## Star History
+## Support the Project
+
+If ALMA helps your AI agents get smarter:
+
+- **Star this repo** - It helps others discover ALMA
+- **[Buy me a coffee](https://buymeacoffee.com/aiagentsprp)** - Support continued development
+- **[Sponsor on GitHub](https://github.com/sponsors/RBKunnela)** - Become an official sponsor
+- **Contribute** - PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+---
+
+## Links
 
-If ALMA helps your AI agents get smarter, consider giving us a star!
+- **Documentation:** [alma-memory.pages.dev](https://alma-memory.pages.dev)
+- **PyPI:** [pypi.org/project/alma-memory](https://pypi.org/project/alma-memory/)
+- **npm:** [@rbkunnela/alma-memory](https://github.com/RBKunnela/ALMA-memory/pkgs/npm/alma-memory)
+- **Issues:** [GitHub Issues](https://github.com/RBKunnela/ALMA-memory/issues)
 
 ---
 
 **Built for AI agents that get better with every task.**
+
+*Created by [@RBKunnela](https://github.com/RBKunnela)*
+
+---
+
+## Technical Documentation
+
+For detailed technical reference including architecture diagrams, API specifications, storage backend configuration, and performance tuning, see the **[Technical Documentation](docs/TECHNICAL.md)**.
+
+---
+
+## Share ALMA
+
+Help other developers discover ALMA:
+
+- **Twitter/X:** "Just found @ALMA_Memory - finally an AI agent memory framework that actually works. Scoped learning, anti-patterns, multi-agent sharing. Way better than Mem0. https://alma-memory.pages.dev"
+- **LinkedIn:** Share how ALMA improved your AI agent workflows
+- **Reddit:** Post in r/MachineLearning, r/LocalLLaMA, r/ClaudeAI, r/artificial
+- **Hacker News:** Submit the landing page - we'd love your upvotes!
+- **Dev.to / Medium:** Write about your experience using ALMA
+
+---
+
+## Keywords
+
+*AI agent memory, persistent memory for LLMs, Mem0 alternative, LangChain memory replacement, agent learning framework, MCP memory server, Claude Code memory, vector database for agents, pgvector memory, Qdrant memory, Pinecone memory, multi-agent memory sharing, AI memory architecture, semantic memory for AI, long-term memory AI agents, memory-augmented AI, retrieval-augmented generation, RAG memory, agentic memory system*