alma-memory 0.2.0__py3-none-any.whl

alma/types.py

@@ -0,0 +1,216 @@
+"""
+ALMA Memory Types
+
+Defines the core data structures for all memory types.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional, List, Dict, Any
+from enum import Enum
+
+
+class MemoryType(Enum):
+    """Categories of memory that agents can store and retrieve."""
+    HEURISTIC = "heuristic"
+    OUTCOME = "outcome"
+    USER_PREFERENCE = "user_preference"
+    DOMAIN_KNOWLEDGE = "domain_knowledge"
+    ANTI_PATTERN = "anti_pattern"
+
+
+@dataclass
+class MemoryScope:
+    """
+    Defines what an agent is allowed to learn.
+
+    Prevents scope creep by explicitly listing allowed and forbidden domains.
+    """
+    agent_name: str
+    can_learn: List[str]
+    cannot_learn: List[str]
+    min_occurrences_for_heuristic: int = 3
+
+    def is_allowed(self, domain: str) -> bool:
+        """Check if learning in this domain is permitted."""
+        if domain in self.cannot_learn:
+            return False
+        if not self.can_learn:  # Empty means all allowed (except cannot_learn)
+            return True
+        return domain in self.can_learn
+
+
+@dataclass
+class Heuristic:
+    """
+    A learned rule: "When condition X, strategy Y works N% of the time."
+
+    Heuristics are only created after min_occurrences validations.
+    """
+    id: str
+    agent: str
+    project_id: str
+    condition: str  # "form with multiple required fields"
+    strategy: str   # "test happy path first, then individual validation"
+    confidence: float  # 0.0 to 1.0
+    occurrence_count: int
+    success_count: int
+    last_validated: datetime
+    created_at: datetime
+    embedding: Optional[List[float]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate success rate from occurrences."""
+        if self.occurrence_count == 0:
+            return 0.0
+        return self.success_count / self.occurrence_count
+
+
+@dataclass
+class Outcome:
+    """
+    Record of a task execution - success or failure with context.
+
+    Outcomes are raw data that can be consolidated into heuristics.
+    """
+    id: str
+    agent: str
+    project_id: str
+    task_type: str  # "api_validation", "form_testing", etc.
+    task_description: str
+    success: bool
+    strategy_used: str
+    duration_ms: Optional[int] = None
+    error_message: Optional[str] = None
+    user_feedback: Optional[str] = None
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    embedding: Optional[List[float]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class UserPreference:
+    """
+    A remembered user constraint or communication preference.
+
+    Persists across sessions so users don't repeat themselves.
+    """
+    id: str
+    user_id: str
+    category: str  # "communication", "code_style", "workflow"
+    preference: str  # "No emojis in documentation"
+    source: str  # "explicit_instruction", "inferred_from_correction"
+    confidence: float = 1.0  # Lower for inferred preferences
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class DomainKnowledge:
+    """
+    Accumulated domain-specific facts within agent's scope.
+
+    Different from heuristics - these are facts, not strategies.
+    """
+    id: str
+    agent: str
+    project_id: str
+    domain: str  # "authentication", "database_schema", etc.
+    fact: str  # "Login endpoint uses JWT with 24h expiry"
+    source: str  # "code_analysis", "documentation", "user_stated"
+    confidence: float = 1.0
+    last_verified: datetime = field(default_factory=datetime.utcnow)
+    embedding: Optional[List[float]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AntiPattern:
+    """
+    What NOT to do - learned from validated failures.
+
+    Helps agents avoid repeating mistakes.
+    """
+    id: str
+    agent: str
+    project_id: str
+    pattern: str  # "Using fixed sleep() for async waits"
+    why_bad: str  # "Causes flaky tests, doesn't adapt to load"
+    better_alternative: str  # "Use explicit waits with conditions"
+    occurrence_count: int
+    last_seen: datetime
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    embedding: Optional[List[float]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class MemorySlice:
+    """
+    A compact, relevant subset of memories for injection into context.
+
+    This is what gets injected per-call - must stay under token budget.
+    """
+    heuristics: List[Heuristic] = field(default_factory=list)
+    outcomes: List[Outcome] = field(default_factory=list)
+    preferences: List[UserPreference] = field(default_factory=list)
+    domain_knowledge: List[DomainKnowledge] = field(default_factory=list)
+    anti_patterns: List[AntiPattern] = field(default_factory=list)
+
+    # Retrieval metadata
+    query: Optional[str] = None
+    agent: Optional[str] = None
+    retrieval_time_ms: Optional[int] = None
+
+    def to_prompt(self, max_tokens: int = 2000) -> str:
+        """
+        Format memories for injection into agent context.
+
+        Respects token budget by prioritizing high-confidence items.
+        """
+        sections = []
+
+        if self.heuristics:
+            h_text = "## Relevant Strategies\n"
+            for h in sorted(self.heuristics, key=lambda x: -x.confidence)[:5]:
+                h_text += f"- When: {h.condition}\n  Do: {h.strategy} (confidence: {h.confidence:.0%})\n"
+            sections.append(h_text)
+
+        if self.anti_patterns:
+            ap_text = "## Avoid These Patterns\n"
+            for ap in self.anti_patterns[:3]:
+                ap_text += f"- Don't: {ap.pattern}\n  Why: {ap.why_bad}\n  Instead: {ap.better_alternative}\n"
+            sections.append(ap_text)
+
+        if self.preferences:
+            p_text = "## User Preferences\n"
+            for p in self.preferences[:5]:
+                p_text += f"- {p.preference}\n"
+            sections.append(p_text)
+
+        if self.domain_knowledge:
+            dk_text = "## Domain Context\n"
+            for dk in self.domain_knowledge[:5]:
+                dk_text += f"- {dk.fact}\n"
+            sections.append(dk_text)
+
+        result = "\n".join(sections)
+
+        # Basic token estimation (rough: 1 token ~ 4 chars)
+        if len(result) > max_tokens * 4:
+            result = result[:max_tokens * 4] + "\n[truncated]"
+
+        return result
+
+    @property
+    def total_items(self) -> int:
+        """Total number of memory items in this slice."""
+        return (
+            len(self.heuristics) +
+            len(self.outcomes) +
+            len(self.preferences) +
+            len(self.domain_knowledge) +
+            len(self.anti_patterns)
+        )

alma_memory-0.2.0.dist-info/METADATA

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: alma-memory
+Version: 0.2.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
+
+> A reusable harness pattern for creating AI agents that learn and improve over time through structured memory - without model weight updates.
+
+## The Harness Pattern
+
+ALMA isn't just agent memory - it's a **generalized framework** for any tool-using workflow:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  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           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**The Flow:**
+1. **Pre-run**: Inject relevant memory slices ("Past successes in similar tasks")
+2. **Run**: Agent acts using tools, logs reflections
+3. **Post-run**: Update memory schema
+4. **Repeat**: Agent appears to "learn" without weight changes
+
+## Why This Matters
+
+```
+Code exists       ≠ Knowledge retained
+Knowledge retained ≠ Knowledge scoped
+Knowledge scoped   ≠ Knowledge retrieved efficiently
+```
+
+ALMA solves all three through **scoped memory injection**. Agents get smarter via better-informed prompts, not model changes.
+
+## Supported Domains
+
+ALMA works for ANY tool-using workflow:
+
+| Domain | Agents | Use Case |
+|--------|--------|----------|
+| **Coding** | Helena, Victor | Testing, API development |
+| **Research** | Researcher | Market analysis, competitive intelligence |
+| **Content** | Copywriter, Documenter | Marketing, documentation |
+| **Operations** | Support | Customer service, automation |
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install alma-memory
+# or from source
+pip install git+https://github.com/RBKunnela/ALMA-memory.git
+```
+
+### Using the Harness Pattern
+
+```python
+from alma import ALMA, create_harness, Context
+
+# Initialize ALMA
+alma = ALMA.from_config(".alma/config.yaml")
+
+# Create a domain-specific harness
+harness = create_harness("coding", "helena", alma)
+
+# Define task context
+context = Context(
+    task="Test the login form validation",
+    project_id="my-app",
+    user_id="developer-1",
+    inputs={"component": "LoginForm", "priority": "high"}
+)
+
+# Run with memory injection
+result = harness.run(context)
+
+# The harness automatically:
+# 1. Retrieved relevant memories (testing strategies, past outcomes)
+# 2. Built the prompt with injected knowledge
+# 3. Will log the outcome for future learning
+```
+
+### Creating Custom Agents
+
+```python
+from alma import (
+    ALMA, Harness, Setting, Agent, MemorySchema, Tool, ToolType
+)
+
+# Define the environment
+setting = Setting(
+    name="Bio Research Environment",
+    description="Tools for biological data analysis",
+    tools=[
+        Tool(
+            name="sequence_search",
+            description="Search genomic databases",
+            tool_type=ToolType.SEARCH,
+        ),
+        Tool(
+            name="structure_analysis",
+            description="Analyze protein structures",
+            tool_type=ToolType.ANALYSIS,
+        ),
+    ],
+    global_constraints=[
+        "Cite all data sources",
+        "Note confidence levels",
+    ],
+)
+
+# Define what this agent can learn
+schema = MemorySchema(
+    domain="bioinformatics",
+    description="Patterns for biological data analysis",
+    learnable_categories=[
+        "search_refinements",
+        "analysis_patterns",
+        "data_interpretation",
+    ],
+    forbidden_categories=[
+        "medical_diagnosis",  # Out of scope
+    ],
+    min_occurrences=5,
+)
+
+# Create the agent
+agent = Agent(
+    name="bio_researcher",
+    role="Bioinformatics Analyst",
+    description="Expert in genomic analysis and protein structure prediction",
+    memory_schema=schema,
+)
+
+# Assemble the harness
+alma = ALMA.from_config(".alma/config.yaml")
+harness = Harness(setting=setting, agent=agent, alma=alma)
+```
+
+### Basic Memory Operations
+
+```python
+from alma import ALMA
+
+alma = ALMA.from_config(".alma/config.yaml")
+
+# Retrieve relevant memories
+memories = alma.retrieve(
+    task="Test the login form validation",
+    agent="helena",
+    top_k=5
+)
+
+# Inject into prompt
+prompt = f"""
+## Your Task
+Test the login form validation
+
+## Relevant Knowledge (from past runs)
+{memories.to_prompt()}
+"""
+
+# After task completion, learn from the outcome
+alma.learn(
+    agent="helena",
+    task="Test login form",
+    outcome="success",
+    strategy_used="Tested empty fields, invalid email, valid submission",
+    feedback="User confirmed tests were thorough"
+)
+```
+
+## 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" |
+
+## Configuration
+
+Create `.alma/config.yaml`:
+
+```yaml
+alma:
+  project_id: "my-project"
+  storage: sqlite  # or "azure" for production
+
+  domains:
+    coding:
+      enabled: true
+      agents: [helena, victor]
+    research:
+      enabled: true
+      agents: [researcher]
+
+  agents:
+    helena:
+      domain: coding
+      can_learn:
+        - testing_strategies
+        - selector_patterns
+      cannot_learn:
+        - backend_logic
+      min_occurrences_for_heuristic: 3
+
+    researcher:
+      domain: research
+      can_learn:
+        - trend_patterns
+        - source_reliability
+      cannot_learn:
+        - code_implementation
+      min_occurrences_for_heuristic: 5
+```
+
+## Storage Backends
+
+| Backend | Use Case | Vector Search |
+|---------|----------|---------------|
+| `azure` | Production | Cosmos DB with vector search |
+| `sqlite` | Local dev | SQLite + FAISS |
+| `file` | Testing | JSON files (no vector search) |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      HARNESS PATTERN                            │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐    │
+│  │ Setting  │  │ Context  │  │  Agent   │  │MemorySchema  │    │
+│  │ (tools)  │  │ (task)   │  │(executor)│  │  (learning)  │    │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────────┘    │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                        ALMA CORE                                │
+│  ┌────────────┐  ┌────────────┐  ┌────────────────────────┐    │
+│  │ Retrieval  │  │  Learning  │  │      Storage           │    │
+│  │  Engine    │  │  Protocol  │  │ (Azure/SQLite/File)    │    │
+│  └────────────┘  └────────────┘  └────────────────────────┘    │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                     MEMORY TYPES                                │
+│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌──────────┐  │
+│  │ Heuristics │  │  Outcomes  │  │Preferences │  │Anti-patt.│  │
+│  └────────────┘  └────────────┘  └────────────┘  └──────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Documentation
+
+- [PRD](docs/architecture/PRD.md) - Full product requirements
+- [Harness Pattern](docs/guides/harness-pattern.md) - Deep dive on the pattern
+- [API Reference](docs/api/) - Coming soon
+
+## Status
+
+| Phase | Description | Status |
+|-------|-------------|--------|
+| 1 | Core Abstractions | Done |
+| 2 | Local Storage (SQLite + FAISS) | Done |
+| 3 | Retrieval Engine | In Progress |
+| 4 | Learning Protocols | Todo |
+| 5 | Agent Integration (Helena + Victor) | Todo |
+| 6 | Azure Cosmos DB | Todo |
+| 7 | Cache Layer | Todo |
+| 8 | Forgetting Mechanism | Todo |
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

alma_memory-0.2.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+alma/__init__.py,sha256=QGUJuT7StZvjzNAwInBgXasEEuoEOMmwMQ9fRtTImQk,1504
+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/harness/__init__.py,sha256=T25gbnat63HA6QeHY5BiaYxM3BODgQmkcR85DIVjsMc,684
+alma/harness/base.py,sha256=rvgLHVVKo0INDDQTzqYIzEpoNkSiJ0DG5qE_-K4Cc5A,11223
+alma/harness/domains.py,sha256=ur6BqClFd7JgH62DQsC5RBJV-IpEbL9uaEHZzZRtyxI,25720
+alma/integration/__init__.py,sha256=bQZKgA4zhUD3AK4lxh4I7PGukUogKFodIDn3Jurlcws,1276
+alma/integration/claude_agents.py,sha256=HdAZVVIOr7W-_oAuDL4J7ZanvvpOjCP_Lfw-N1TMekI,13318
+alma/integration/helena.py,sha256=rDCYy8Y7_f3xeCzahahio_0OIUury-dMhU7Z_EjWc5w,11885
+alma/integration/victor.py,sha256=Z3FBso38eYs4X6He2qvl_O3Lu9_o5X1dWHvf3PnI0kw,13073
+alma/learning/__init__.py,sha256=GU33u8KUyDgnUASXfAXZ5rMF3sjkdWMzqR5aWAwjWPU,1870
+alma/learning/forgetting.py,sha256=_7BVezNjoEk2AGVARVPr255af3O51vtKR6LW8dMrSwU,45513
+alma/learning/heuristic_extractor.py,sha256=lKM2hGihFjeTolOl58GImfPkaSQOsEqCCjuYPhskJf0,11881
+alma/learning/protocols.py,sha256=yr5JpHQB5ktYtkmSaas6AUp0iWPyoN7ZU39nEdRwUko,10328
+alma/learning/validation.py,sha256=cv4mMTr3hRlC3AxWHG7-w-k_b-dNkowRh-idC18hN6Y,11028
+alma/mcp/__init__.py,sha256=USCtSVAKaW1eFKgdqm50krlufPeccfGw5yDZ4BC2KwE,947
+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/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/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_memory-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

alma_memory-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+alma