Name: ALMA - Agent Learning Memory Architecture
Author: RBKunnela

The Same Mistakes. Every Session.

Why I built ALMA

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:

x Helena would use sleep(5000) for waits, causing flaky tests
x Victor would forget that the API uses JWT with 24-hour expiry
x 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. Helena could "learn" database queries she'd never use. I looked at LangChain Memory. It's for conversation context, not long-term learning. Different problem.

Nothing fit. So I built ALMA - Agent Learning Memory Architecture. The core insight: AI agents don't need to modify their weights to "learn." They need smart prompts built from relevant past experiences.

How ALMA Works

Three simple phases. No model modifications.

Before Task

Retrieve Memories

ALMA finds relevant past experiences, strategies that worked, and anti-patterns to avoid.

"Incremental validation worked"
"Don't use sleep() - flaky"

During Task

Execute with Context

Memories are injected into prompts. The agent executes with accumulated knowledge.

Agent uses explicit waits
Tests pass on first try

After Task

Learn from Outcome

Success becomes a new heuristic. Failure becomes an anti-pattern with what to do instead.

Heuristic saved
Future tasks benefit

What Makes ALMA Different

Purpose-built for AI agents that need to learn, remember, and improve.

Scoped Learning

Define what each agent can and cannot learn. Helena learns testing, not database queries.

can_learn: [testing, selectors]
cannot_learn: [backend_logic]

Anti-Pattern Tracking

Explicitly record what NOT to do, why it's bad, and what to do instead.

pattern: "Using sleep()"
why_bad: "Flaky tests"
instead: "Explicit waits"

Multi-Agent Sharing

Senior agents share knowledge with juniors. Hierarchical memory inheritance.

senior: share_with: [junior]
junior: inherit_from: [senior]

Workflow Checkpoints

Save state mid-workflow, resume after failures. Perfect for complex multi-step tasks.

alma.checkpoint(workflow_id, state)
alma.resume(workflow_id)

MCP Integration

Native MCP server with 16 tools. Works directly with Claude Code.

python -m alma.mcp
# 16 tools ready to use

6 Vector Backends

PostgreSQL, Qdrant, Pinecone, Chroma, SQLite, Azure Cosmos. Deploy anywhere.

PostgreSQL Qdrant Pinecone Chroma SQLite Azure

5

Memory Types

16

MCP Tools

4

Graph Backends

6

Domain Schemas

ALMA vs Alternatives

See how ALMA compares to Mem0 and LangChain Memory.

Feature	ALMA v0.6.0	Mem0	LangChain Memory
Memory Scoping	can_learn / cannot_learn	Basic isolation	None
Anti-Pattern Learning	Yes	No	No
Multi-Agent Sharing	inherit_from + share_with	No	No
Workflow Checkpoints	Yes	No	No
MCP Integration	16 tools	No	No
TypeScript SDK	Full-featured	No	Limited
Vector Backends	6 options	Limited	Via integrations
Graph Memory	Neo4j, Memgraph, Kuzu	Limited	Entity memory
Event System	Webhooks + callbacks	No	No
License	MIT (fully open)	Partially open	MIT

Ready to give your agents real memory?

Get Started

Get Started in 60 Seconds

Install ALMA and start giving your agents memory.

Python

pip install alma-memory

TypeScript / Node.js

npm install @rbkunnela/alma-memory

from alma import ALMA

# Initialize ALMA
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 memories into your prompt
prompt = f"""
## Your Task
Test the login form validation

## Knowledge from Past Runs
{memories.to_prompt()}
"""

# Run your agent with the enriched prompt
result = run_agent(prompt)

# After task: Learn from the outcome
alma.learn(
    agent="helena",
    task="Test login form",
    outcome="success",
    strategy_used="Tested empty fields, invalid email, valid submission"
)

# Track anti-patterns (what NOT to do)
alma.add_anti_pattern(
    agent="helena",
    pattern="Using sleep() for async waits",
    why_bad="Causes flaky tests, wastes time",
    better_alternative="Use explicit waits with conditions"
)

import { ALMA } from '@rbkunnela/alma-memory';

// Create client
const alma = new ALMA({
  baseUrl: 'http://localhost:8765',
  projectId: 'my-project'
});

// Before task: Retrieve relevant memories
const memories = await alma.retrieve({
  query: 'authentication flow testing',
  agent: 'helena',
  topK: 5
});

// Use memories in your agent prompt
const prompt = `
## Your Task
Test the login form validation

## Knowledge from Past Runs
${memories.toPrompt()}
`;

// Run your agent...
const result = await runAgent(prompt);

// After task: Learn from outcome
await alma.learn({
  agent: 'helena',
  task: 'Test login form',
  outcome: 'success',
  strategyUsed: 'Tested empty fields, invalid email, valid submission'
});

// Add preferences and knowledge
await alma.addPreference({
  userId: 'user-123',
  category: 'code_style',
  preference: 'Use TypeScript strict mode'
});

await alma.addKnowledge({
  agent: 'helena',
  domain: 'authentication',
  fact: 'API uses JWT with 24h expiry'
});

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

// Add to .mcp.json for Claude Code
{
  "mcpServers": {
    "alma-memory": {
      "command": "python",
      "args": ["-m", "alma.mcp", "--config", ".alma/config.yaml"]
    }
  }
}

# .alma/config.yaml
alma:
  project_id: "my-project"
  storage: sqlite
  embedding_provider: local
  storage_dir: .alma

  agents:
    helena:
      domain: coding
      can_learn:
        - testing_strategies
        - selector_patterns
      cannot_learn:
        - backend_logic
      share_with: [qa_lead]

Deploy Anywhere

6 vector database backends. From local development to enterprise scale.

PostgreSQL + pgvector

Q

Qdrant Vector DB

Pinecone Serverless

Chroma Lightweight

SQLite + FAISS

Azure Cosmos Enterprise

Ready to Build Smarter Agents?

Stop watching your AI make the same mistakes. Give your agents memory that persists, learns, and improves.

Star on GitHub PyPI npm

Support continued development: Buy me a coffee

AI Agents That Actually Learn