alma-memory 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

alma_memory-0.3.0.dist-info/METADATA

@@ -0,0 +1,438 @@
+Metadata-Version: 2.4
+Name: alma-memory
+Version: 0.3.0
+Summary: Agent Learning Memory Architecture - Persistent memory for AI agents
+Author-email: RBKunnela <aiagentsprompt@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/RBKunnela/ALMA-memory
+Project-URL: Documentation, https://github.com/RBKunnela/ALMA-memory/tree/main/docs
+Project-URL: Repository, https://github.com/RBKunnela/ALMA-memory
+Project-URL: Issues, https://github.com/RBKunnela/ALMA-memory/issues
+Keywords: ai,agents,memory,learning,llm,azure,claude
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: local
+Requires-Dist: sentence-transformers>=2.2.0; extra == "local"
+Requires-Dist: faiss-cpu>=1.7.4; extra == "local"
+Provides-Extra: azure
+Requires-Dist: azure-cosmos>=4.5.0; extra == "azure"
+Requires-Dist: azure-identity>=1.15.0; extra == "azure"
+Requires-Dist: azure-keyvault-secrets>=4.7.0; extra == "azure"
+Requires-Dist: openai>=1.0.0; extra == "azure"
+Provides-Extra: mcp
+Requires-Dist: pydantic>=2.0.0; extra == "mcp"
+Requires-Dist: aiohttp>=3.9.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: alma-memory[azure,dev,local,mcp]; extra == "all"
+
+# ALMA - Agent Learning Memory Architecture
+
+[![PyPI version](https://badge.fury.io/py/alma-memory.svg)](https://pypi.org/project/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)
+
+> Persistent memory for AI agents that learn and improve over time - without model weight updates.
+
+## What is ALMA?
+
+ALMA is a **memory framework** that makes AI agents appear to "learn" by:
+1. **Storing** outcomes, strategies, and knowledge from past tasks
+2. **Retrieving** relevant memories before each new task
+3. **Injecting** that knowledge into prompts
+4. **Learning** from new outcomes to improve future performance
+
+**No fine-tuning. No model changes. Just smarter prompts.**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  BEFORE TASK: Retrieve relevant memories                        │
+│  ├── "Last time you tested forms, incremental validation worked"│
+│  ├── "User prefers verbose output"                              │
+│  └── "Don't use sleep() - causes flaky tests"                   │
+├─────────────────────────────────────────────────────────────────┤
+│  DURING TASK: Agent executes with injected knowledge            │
+├─────────────────────────────────────────────────────────────────┤
+│  AFTER TASK: Learn from outcome                                 │
+│  └── Success? → New heuristic. Failure? → Anti-pattern.         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+```bash
+pip install alma-memory
+```
+
+## Quick Start
+
+```python
+from alma import ALMA
+
+# Initialize
+alma = ALMA.from_config(".alma/config.yaml")
+
+# Before task: Get relevant memories
+memories = alma.retrieve(
+    task="Test the login form validation",
+    agent="helena",
+    top_k=5
+)
+
+# Inject into your prompt
+prompt = f"""
+## Your Task
+Test the login form validation
+
+## Knowledge from Past Runs
+{memories.to_prompt()}
+"""
+
+# After task: Learn from outcome
+alma.learn(
+    agent="helena",
+    task="Test login form",
+    outcome="success",
+    strategy_used="Tested empty fields, invalid email, valid submission",
+)
+```
+
+## Features
+
+### Core Memory System
+
+| Feature | Description |
+|---------|-------------|
+| **5 Memory Types** | Heuristics, Outcomes, Preferences, Domain Knowledge, Anti-patterns |
+| **Semantic Search** | Vector similarity for relevant memory retrieval |
+| **Scoped Learning** | Agents only learn from their domain (Helena can't learn backend) |
+| **Confidence Decay** | Old memories fade, recent ones stay strong |
+| **Forgetting** | Automatic cleanup of low-value memories |
+
+### Storage Backends
+
+| Backend | Use Case | Vector Search |
+|---------|----------|---------------|
+| **SQLite + FAISS** | Local development | Yes |
+| **Azure Cosmos DB** | Production | Yes (native) |
+| **File-based** | Testing/Simple use | No |
+
+### Domain Memory Factory (NEW in v0.3.0)
+
+Create ALMA instances for any domain - not just coding:
+
+```python
+from alma.domains import DomainMemoryFactory, get_research_schema
+
+# Pre-built schemas
+factory = DomainMemoryFactory()
+alma = factory.create_alma(get_research_schema(), "my-research-project")
+
+# Or create custom domains
+schema = factory.create_schema("sales", {
+    "entity_types": [
+        {"name": "lead", "attributes": ["stage", "value"]},
+        {"name": "objection", "attributes": ["type", "response"]},
+    ],
+    "learning_categories": [
+        "objection_handling",
+        "closing_techniques",
+        "qualification_patterns",
+    ],
+})
+```
+
+**Pre-built schemas:** `coding`, `research`, `sales`, `general`, `customer_support`, `content_creation`
+
+### Progress Tracking (NEW in v0.3.0)
+
+Track work items and get intelligent next-task suggestions:
+
+```python
+from alma.progress import ProgressTracker
+
+tracker = ProgressTracker("my-project")
+
+# Create work items
+item = tracker.create_work_item(
+    title="Fix authentication bug",
+    description="Login fails on mobile devices",
+    priority=80,
+    agent="Victor",
+)
+
+# Update status
+tracker.update_status(item.id, "in_progress")
+
+# Get next task (by priority, quick wins, or unblock others)
+next_task = tracker.get_next_item(strategy="priority")
+
+# Get progress summary
+summary = tracker.get_progress_summary()
+print(f"Done: {summary.done}/{summary.total} ({summary.completion_percentage}%)")
+```
+
+### Session Handoff (NEW in v0.3.0)
+
+Maintain context across sessions - no more "starting fresh":
+
+```python
+from alma.session import SessionManager
+
+manager = SessionManager("my-project")
+
+# Start session (loads previous context)
+context = manager.start_session(agent="Helena", goal="Complete auth testing")
+
+# Previous session info is available
+if context.previous_handoff:
+    print(f"Last action: {context.previous_handoff.last_action}")
+    print(f"Blockers: {context.previous_handoff.blockers}")
+
+# Track decisions and blockers during work
+manager.update_session("Helena", context.session_id,
+    decision="Using OAuth mock for testing",
+    blocker="Staging API is down",
+)
+
+# End session with handoff for next time
+manager.create_handoff("Helena", context.session_id,
+    last_action="completed_oauth_tests",
+    last_outcome="success",
+    next_steps=["Test refresh tokens", "Add error cases"],
+)
+```
+
+### MCP Server Integration
+
+Expose ALMA to Claude Code or any MCP-compatible client:
+
+```bash
+# Start MCP server
+python -m alma.mcp --config .alma/config.yaml
+```
+
+```json
+// .mcp.json
+{
+  "mcpServers": {
+    "alma-memory": {
+      "command": "python",
+      "args": ["-m", "alma.mcp", "--config", ".alma/config.yaml"]
+    }
+  }
+}
+```
+
+**Available MCP Tools:**
+- `alma_retrieve` - Get memories for a task
+- `alma_learn` - Record task outcome
+- `alma_add_preference` - Add user preference
+- `alma_add_knowledge` - Add domain knowledge
+- `alma_forget` - Prune stale memories
+- `alma_stats` - Get memory statistics
+- `alma_health` - Health check
+
+## Memory Types
+
+| Type | What It Stores | Example |
+|------|----------------|---------|
+| **Heuristic** | Learned strategies | "For forms with >5 fields, test validation incrementally" |
+| **Outcome** | Task results | "Login test succeeded using JWT token strategy" |
+| **Preference** | User constraints | "User prefers verbose test output" |
+| **Domain Knowledge** | Accumulated facts | "Login uses OAuth 2.0 with 24h token expiry" |
+| **Anti-pattern** | What NOT to do | "Don't use sleep() for async waits - causes flaky tests" |
+
+## The Harness Pattern
+
+ALMA implements a generalized harness pattern for any tool-using agent:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  1. SETTING        Fixed environment: tools, constraints        │
+├─────────────────────────────────────────────────────────────────┤
+│  2. CONTEXT        Ephemeral per-run inputs: task, user         │
+├─────────────────────────────────────────────────────────────────┤
+│  3. AGENT          The executor with scoped intelligence        │
+├─────────────────────────────────────────────────────────────────┤
+│  4. MEMORY SCHEMA  Domain-specific learning structure           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+```python
+from alma import create_harness, Context
+
+# Create domain-specific harness
+harness = create_harness("coding", "helena", alma)
+
+# Run with automatic memory injection
+result = harness.run(Context(
+    task="Test the login form validation",
+    project_id="my-app",
+))
+```
+
+## Configuration
+
+Create `.alma/config.yaml`:
+
+```yaml
+alma:
+  project_id: "my-project"
+  storage: sqlite  # or "azure" for production
+
+  agents:
+    helena:
+      domain: coding
+      can_learn:
+        - testing_strategies
+        - selector_patterns
+      cannot_learn:
+        - backend_logic
+      min_occurrences_for_heuristic: 3
+
+    victor:
+      domain: coding
+      can_learn:
+        - api_patterns
+        - database_queries
+      cannot_learn:
+        - frontend_selectors
+      min_occurrences_for_heuristic: 3
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        ALMA v0.3.0                              │
+├─────────────────────────────────────────────────────────────────┤
+│  HARNESS LAYER                                                  │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐    │
+│  │ Setting  │  │ Context  │  │  Agent   │  │MemorySchema  │    │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────────┘    │
+├─────────────────────────────────────────────────────────────────┤
+│  NEW IN v0.3.0                                                  │
+│  ┌──────────────┐  ┌────────────────┐  ┌───────────────────┐   │
+│  │ Progress     │  │ Session        │  │ Domain Memory     │   │
+│  │ Tracking     │  │ Handoff        │  │ Factory           │   │
+│  └──────────────┘  └────────────────┘  └───────────────────┘   │
+├─────────────────────────────────────────────────────────────────┤
+│  CORE LAYER                                                     │
+│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌──────────┐  │
+│  │ Retrieval  │  │  Learning  │  │  Caching   │  │Forgetting│  │
+│  │  Engine    │  │  Protocol  │  │   Layer    │  │Mechanism │  │
+│  └────────────┘  └────────────┘  └────────────┘  └──────────┘  │
+├─────────────────────────────────────────────────────────────────┤
+│  STORAGE LAYER                                                  │
+│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐    │
+│  │ SQLite + FAISS │  │  Azure Cosmos  │  │   File-based   │    │
+│  └────────────────┘  └────────────────┘  └────────────────┘    │
+├─────────────────────────────────────────────────────────────────┤
+│  INTEGRATION LAYER                                              │
+│  ┌────────────────────────────────────────────────────────┐    │
+│  │                    MCP Server                           │    │
+│  └────────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Development Status
+
+| Phase | Description | Status |
+|-------|-------------|--------|
+| 1 | Core Abstractions | ✅ Done |
+| 2 | Local Storage (SQLite + FAISS) | ✅ Done |
+| 3 | Retrieval Engine | ✅ Done |
+| 4 | Learning Protocols | ✅ Done |
+| 5 | Agent Integration | ✅ Done |
+| 6 | Azure Cosmos DB | ✅ Done |
+| 7 | Cache Layer | ✅ Done |
+| 8 | Forgetting Mechanism | ✅ Done |
+| 9 | MCP Server + Testing Suite | ✅ Done |
+| 10 | Progress, Sessions, Domains | ✅ Done |
+| 11 | Initializer Agent Pattern | Planned |
+| 12 | Forward-Looking Confidence | Planned |
+
+## API Reference
+
+### Core
+
+```python
+# Initialize
+alma = ALMA.from_config(".alma/config.yaml")
+
+# Retrieve memories
+memories = alma.retrieve(task, agent, top_k=5)
+
+# Learn from outcome
+alma.learn(agent, task, outcome, strategy_used, feedback=None)
+
+# Add knowledge directly
+alma.add_preference(user_id, category, preference)
+alma.add_domain_knowledge(agent, domain, fact)
+
+# Memory hygiene
+alma.forget(agent, older_than_days=90, min_confidence=0.3)
+```
+
+### Progress Tracking
+
+```python
+from alma.progress import ProgressTracker, WorkItem
+
+tracker = ProgressTracker("project-id")
+item = tracker.create_work_item(title, description, priority=50)
+tracker.update_status(item.id, "in_progress")  # or "done", "blocked"
+next_item = tracker.get_next_item(strategy="priority")
+summary = tracker.get_progress_summary(agent="helena")
+```
+
+### Session Management
+
+```python
+from alma.session import SessionManager
+
+manager = SessionManager("project-id")
+context = manager.start_session(agent, goal)
+manager.update_session(agent, session_id, decision=..., blocker=...)
+manager.create_handoff(agent, session_id, last_action, outcome, next_steps)
+reload_str = manager.get_quick_reload(agent)
+```
+
+### Domain Factory
+
+```python
+from alma.domains import DomainMemoryFactory, get_coding_schema
+
+factory = DomainMemoryFactory()
+schema = get_coding_schema()  # or research, sales, general
+alma = factory.create_alma(schema, "project-id")
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+**Built for AI agents that get better with every task.**

{alma_memory-0.2.0.dist-info → alma_memory-0.3.0.dist-info}/RECORD

@@ -1,8 +1,12 @@
-alma/__init__.py,sha256=QGUJuT7StZvjzNAwInBgXasEEuoEOMmwMQ9fRtTImQk,1504
+alma/__init__.py,sha256=NORUFhIujFb2ZQdft_mM6If48dGv4AAVnCssaWgiyMg,2500
 alma/core.py,sha256=-lAYOdnNYDz0ziVQFybLNF_2cDbM8-lIw5xvLuiXZKY,9638
 alma/types.py,sha256=hdBP1dwvYquS7Zej4xb6DM4Bfyx6C2OIFi3vFYo9DMk,6769
 alma/config/__init__.py,sha256=MQ7zjiIFlUnjeI_Nxn4ig0HAmYeUuS7_FVNjYi8Ik3A,99
 alma/config/loader.py,sha256=OJPXTSKrBunl6LMvyb-avSOyH1Pr0IpUZIK9UOmB-LE,4884
+alma/domains/__init__.py,sha256=wDvWGshubbbEcUv_7vUdnj_Np5Ovkqp8w9VwFCv_JOs,623
+alma/domains/factory.py,sha256=dYhsqW8K3VmfzP6zwBzfddkDZBuPjoL_K7jdB6SFne0,10843
+alma/domains/schemas.py,sha256=OOvnddjBwJHSH99h0fZ1EFQgkCPyZPPx3Lc4210Rn0U,13040
+alma/domains/types.py,sha256=s4ToTMLPzJRj1u4yfFTkiQhK2bjcF0O17zaUFloBtOk,8999
 alma/harness/__init__.py,sha256=T25gbnat63HA6QeHY5BiaYxM3BODgQmkcR85DIVjsMc,684
 alma/harness/base.py,sha256=rvgLHVVKo0INDDQTzqYIzEpoNkSiJ0DG5qE_-K4Cc5A,11223
 alma/harness/domains.py,sha256=ur6BqClFd7JgH62DQsC5RBJV-IpEbL9uaEHZzZRtyxI,25720
@@ -20,17 +24,23 @@ alma/mcp/__main__.py,sha256=OKNXBY3GBJJKhAjIpGeKYcK02dX_83eOwUXkUXpV54A,3946
 alma/mcp/resources.py,sha256=tdJoBA55qRcdwXCPyaFJ2hR23oQRqfiNUTzHo-h5qfs,3460
 alma/mcp/server.py,sha256=4LPs2J53I4fTXVB5P-1mZibce-FVWrPhFWCoUKHy9TM,19043
 alma/mcp/tools.py,sha256=UEB9NzcjxcpuAiie6sJ_gGdjfP6Ey0ajgp8hZRx3NHE,9452
+alma/progress/__init__.py,sha256=6cdZ4ON__ARzZRfLOOFcIguQ2Z8xie2CwIvUVCJJWhM,371
+alma/progress/tracker.py,sha256=0wKXqwEQePAYD7lc9DcBGhpqjvcQN47W-UT6p85lp00,19137
+alma/progress/types.py,sha256=cVu-dLrrrsTJ4n25rwaQdWMYTEl2Z4JwYZxJhM83Vfs,7088
 alma/retrieval/__init__.py,sha256=lhfJh7Lfi4d0UYzhgVxKPVCO3959eJwCH0VzK4mgTio,1006
 alma/retrieval/cache.py,sha256=mJ-hJUaoX1aUlcQjYsrrYQBKb8F3qIJJe46bSQ2RMg4,34645
 alma/retrieval/embeddings.py,sha256=S7KvogxBNoDP2r5ANwuH0hFdzqsAGXzAqAA8BY0_zMI,6464
 alma/retrieval/engine.py,sha256=RHkCaBbhYMHA44t8CU1W7dxMuUj1yvZ7p_v52cC23bY,9659
 alma/retrieval/scoring.py,sha256=VG41Vq1mV0DgLv0cM7m89KLwRNqOWaLboSRNhoC0cy8,10102
+alma/session/__init__.py,sha256=1kKfjacWOd0WBWs3Yv_d_t_CaUTOWeGb0DCoKxRfvp8,352
+alma/session/manager.py,sha256=O6Onh7rnQIr_J5L2IahiuxsH7pi8-G_VmGavp_QEsQs,12637
+alma/session/types.py,sha256=lLcWK64C5-ycItJmvHAHgC6L-y3toTc4kKttp2Fvgic,9464
 alma/storage/__init__.py,sha256=PtKICN39q2MQ7CuUmFnERQMIfo8Tbpv_Ro61jLLvUvQ,528
 alma/storage/azure_cosmos.py,sha256=GAeheRabaWXKsXLS66qtl8ALzVk2QM6bw3sgC6ImpSI,32805
 alma/storage/base.py,sha256=-1Xi3zQFdFgdkIWvqLhNNq9SPdjaIYoagijPMKA3I8M,8960
 alma/storage/file_based.py,sha256=g-1dkmu68T6ePhyvh40o_u-THqK1WbXtt4xfccChySM,20709
-alma/storage/sqlite_local.py,sha256=qovQ_vhq67zsrhZLxMtFaCR-9ZPpuV1EAknxmRouqEA,32820
-alma_memory-0.2.0.dist-info/METADATA,sha256=jQQOgv5q1ODVlLdM6lUfdapw4MBAv1HJCmrBR332W0c,12555
-alma_memory-0.2.0.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-alma_memory-0.2.0.dist-info/top_level.txt,sha256=5oN68LXctTl8a8i1LA-5WqSaP-pDA-J0x1AfCFfLm4A,5
-alma_memory-0.2.0.dist-info/RECORD,,
+alma/storage/sqlite_local.py,sha256=ppqUcXbuiqN6p7tEWu0r1MoMQTCXc-XDYkQe0Tq93ps,36557
+alma_memory-0.3.0.dist-info/METADATA,sha256=t2GYuoFkI6VvHBjrwrhF21GPpxOHD6q8J5daBOQEOoA,17731
+alma_memory-0.3.0.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+alma_memory-0.3.0.dist-info/top_level.txt,sha256=5oN68LXctTl8a8i1LA-5WqSaP-pDA-J0x1AfCFfLm4A,5
+alma_memory-0.3.0.dist-info/RECORD,,