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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alma-memory
-Version: 0.5.1
+Version: 0.7.0
 Summary: Agent Learning Memory Architecture - Persistent memory for AI agents
 Author-email: RBKunnela <aiagentsprompt@gmail.com>
 License: MIT
@@ -61,12 +61,65 @@ Requires-Dist: alma-memory[azure,chroma,dev,local,mcp,observability,pinecone,pos
 # 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.**
 
 ---
 
@@ -91,65 +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
-  - Memgraph backend for high-performance in-memory graphs
-  - Kuzu backend for embedded graph storage (no server required)
-  - In-memory backend for testing
-  - Factory function `create_graph_backend()` for easy setup
-
-- **Testing Module** (`alma/testing/`)
-  - `MockStorage` - In-memory storage backend for isolated testing
-  - `MockEmbedder` - Deterministic fake embedding provider
-  - Factory functions for creating test data with sensible defaults
-
-### 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.
 
@@ -205,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
 ```
 
 ---
@@ -252,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({
@@ -536,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 |
@@ -547,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
@@ -677,7 +763,7 @@ print(f"Recommendation: {signal.recommendation}")
 
 ```
 +-------------------------------------------------------------------------+
-|                          ALMA v0.5.0                                    |
+|                          ALMA v0.6.0                                    |
 +-------------------------------------------------------------------------+
 |  HARNESS LAYER                                                          |
 |  +-----------+  +-----------+  +-----------+  +----------------+        |
@@ -843,6 +929,11 @@ chroma:
 | 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 |
 
 ---
 
@@ -907,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
 
@@ -930,10 +1028,50 @@ MIT
 
 ---
 
-## Star History
+## Support the Project
 
-If ALMA helps your AI agents get smarter, consider giving us a star!
+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
+
+- **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*