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.
