alma-memory 0.3.0

Agent Learning Memory Architecture - Persistent memory for AI agents

ALMA - Agent Learning Memory Architecture

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

pip install alma-memory

Quick Start

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:

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:

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":

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:

# Start MCP server
python -m alma.mcp --config .alma/config.yaml

// .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           │
└─────────────────────────────────────────────────────────────────┘

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:

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

# 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

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

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

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 for guidelines.

---

Built for AI agents that get better with every task.