📖 Documentation · 🔧 Technical Reference · 📦 PyPI · 📦 npm · ☕ Support

ALMA is the answer. If you've tried Mem0 or LangChain Memory and found them lacking for production AI agents, ALMA was built specifically to solve those gaps:

See detailed comparisons: ALMA vs Mem0 · ALMA vs LangChain Memory

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:

• Helena would use sleep(5000) for waits, causing flaky tests
• Victor would forget that the API uses JWT with 24-hour expiry
• 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, no anti-pattern tracking, no multi-agent sharing. I looked at LangChain Memory. It's for conversation context, not long-term learning.

Nothing fit. So I built ALMA.

The core insight: AI agents don't need to modify their weights to "learn." They need smart prompts built from relevant past experiences.

ALMA isn't just another memory framework. Here's what sets it apart from alternatives like Mem0:

Bottom line: ALMA is purpose-built for AI agents that need to learn, remember, and improve - not just store and retrieve.

The key insight: Most solutions treat memory as "store embeddings, retrieve similar." ALMA treats it as "teach agents to improve within safe boundaries."

The major theme of v0.6.0 is multi-agent workflow support - enabling agents to coordinate across long-running tasks with checkpoints, state merging, and artifact tracking.

• Checkpoint & Resume (alma/workflow/)

  • Save workflow state at any point: alma.checkpoint(workflow_id, state, metadata)
  • Resume from checkpoints after failures or handoffs: alma.resume(workflow_id)
  • Automatic cleanup of old checkpoints: alma.cleanup_checkpoints(older_than_days=7)

• State Reducers for Multi-Agent Workflows

  • Merge states from parallel agents: alma.merge_states(workflow_id, states, reducer)
  • Built-in reducers: latest_wins, merge_lists, priority_agent
  • Custom reducer functions for complex merge logic

• Artifact Linking

  • Link outputs to workflows: alma.link_artifact(workflow_id, artifact_type, ref)
  • Artifact types: code, test, document, config, deployment
  • Retrieve all artifacts: alma.get_artifacts(workflow_id)

• Scoped Retrieval

  • Filter memories by workflow context: alma.retrieve_scoped(query, scope)
  • Scopes: workflow_only, agent_only, project_wide

• Session Persistence

  • Session handoffs now persist to storage backend
  • Lazy loading for performance
  • Survives process restarts

• MCP Workflow Tools (8 new tools)

  • alma_consolidate, alma_checkpoint, alma_resume
  • alma_merge_states, alma_workflow_learn
  • alma_link_artifact, alma_get_artifacts
  • alma_cleanup_checkpoints, alma_retrieve_scoped

• TypeScript SDK v0.6.0 (packages/alma-memory-js/)

  • Full workflow API parity with Python SDK
  • 9 new methods: consolidate(), checkpoint(), resume(), mergeStates(), workflowLearn(), linkArtifact(), getArtifacts(), cleanupCheckpoints(), retrieveScoped()
  • 25+ new TypeScript types for workflow context
  • Published to GitHub Packages: @rbkunnela/alma-memory

See CHANGELOG.md for the complete history.

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.           |
+---------------------------------------------------------------------+

pip install alma-memory

With optional backends:

# Local development
pip install alma-memory[local]     # SQLite + FAISS + local embeddings

# Production databases
pip install alma-memory[postgres]  # PostgreSQL + pgvector
pip install alma-memory[qdrant]    # Qdrant vector database
pip install alma-memory[pinecone]  # Pinecone vector database
pip install alma-memory[chroma]    # ChromaDB

# Enterprise
pip install alma-memory[azure]     # Azure Cosmos DB + Azure OpenAI

# Everything
pip install alma-memory[all]

TypeScript/JavaScript (via GitHub Packages):

# Configure npm for the scope (one-time)
echo "@rbkunnela:registry=https://npm.pkg.github.com" >> ~/.npmrc

# Install
npm install @rbkunnela/alma-memory
# or
yarn add @rbkunnela/alma-memory

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",
)

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

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

// Retrieve memories
const memories = await alma.retrieve({
  query: 'authentication flow',
  agent: 'dev-agent',
  topK: 5
});

// Learn from outcomes
await alma.learn({
  agent: 'dev-agent',
  task: 'Implement OAuth',
  outcome: 'success',
  strategyUsed: 'Used passport.js middleware'
});

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

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

Agents only learn within their defined domains. Helena (frontend tester) cannot learn backend logic:

agents:
  helena:
    domain: coding
    can_learn:
      - testing_strategies
      - selector_patterns
    cannot_learn:
      - backend_logic
      - database_queries

Enable agents to share knowledge hierarchically:

agents:
  senior_dev:
    can_learn: [architecture, best_practices]
    share_with: [junior_dev, qa_agent]  # Others can read my memories

  junior_dev:
    can_learn: [coding_patterns]
    inherit_from: [senior_dev]  # I can read senior's memories

# Junior dev retrieves memories (includes senior's shared memories)
memories = alma.retrieve(
    task="Implement user authentication",
    agent="junior_dev",
    include_shared=True  # Include inherited memories
)

# Shared memories are marked with origin
for mem in memories.heuristics:
    if mem.metadata.get('shared_from'):
        print(f"Learned from {mem.metadata['shared_from']}: {mem.strategy}")

Automatically deduplicate and merge similar memories using LLM intelligence:

from alma.consolidation import ConsolidationEngine

engine = ConsolidationEngine(
    storage=alma.storage,
    llm_client=my_llm_client  # Optional: for intelligent merging
)

# Consolidate heuristics for an agent
result = await engine.consolidate(
    agent="helena",
    project_id="my-project",
    memory_type="heuristics",
    similarity_threshold=0.85,  # Group memories above this similarity
    use_llm=True,               # Use LLM for intelligent merging
    dry_run=False               # Set True to preview without changes
)

print(f"Merged {result.merged_count} memories from {result.groups_found} groups")

Features:

• Cosine similarity-based grouping
• LLM-powered intelligent merging (preserves important nuances)
• Provenance tracking (merged_from metadata)
• Support for heuristics, domain_knowledge, and anti_patterns

React to memory changes with webhooks or in-process callbacks:

from alma.events import get_emitter, MemoryEventType

def on_memory_created(event):
    print(f"Memory created: {event.memory_id} by {event.agent}")
    # Trigger downstream processes, update caches, etc.

emitter = get_emitter()
emitter.subscribe(MemoryEventType.CREATED, on_memory_created)
emitter.subscribe(MemoryEventType.CONSOLIDATED, on_consolidation)

from alma.events import WebhookConfig, WebhookManager, get_emitter

manager = WebhookManager()
manager.add_webhook(WebhookConfig(
    url="https://your-app.com/alma-webhook",
    events=[MemoryEventType.CREATED, MemoryEventType.UPDATED],
    secret="your-webhook-secret",  # For HMAC signature verification
    retry_count=3,
    retry_delay=5.0
))
manager.start(get_emitter())

Event Types:

• CREATED - New memory stored
• UPDATED - Memory modified
• DELETED - Memory removed
• ACCESSED - Memory retrieved
• CONSOLIDATED - Memories merged

Capture entity relationships for complex reasoning:

from alma.graph import create_graph_backend, BackendGraphStore, EntityExtractor

# Create graph backend - multiple options available:

# Neo4j (production, hosted)
backend = create_graph_backend(
    "neo4j",
    uri="neo4j+s://xxx.databases.neo4j.io",
    username="neo4j",
    password="your-password"
)

# Memgraph (high-performance, in-memory)
# backend = create_graph_backend("memgraph", uri="bolt://localhost:7687")

# Kuzu (embedded, no server required)
# backend = create_graph_backend("kuzu", database_path="./my_graph_db")

# In-memory (testing)
# backend = create_graph_backend("memory")

# Create store with backend
graph = BackendGraphStore(backend)

# Extract entities and relationships from text
extractor = EntityExtractor()
entities, relationships = extractor.extract(
    "Alice from Acme Corp reviewed the PR that Bob submitted."
)

# Store in graph
for entity in entities:
    graph.add_entity(entity)
for rel in relationships:
    graph.add_relationship(rel)

# Query relationships
alice_relations = graph.get_relationships("alice", relationship_type="WORKS_FOR")

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",
))

Expose ALMA to Claude Code or any MCP-compatible client:

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 (16 total):

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

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

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}")

# 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"],
)

Automatically extract and learn from conversations:

from alma.extraction import AutoLearner

alma = ALMA.from_config(".alma/config.yaml")
auto_learner = AutoLearner(alma)

# After a conversation, automatically extract learnings
results = auto_learner.learn_from_conversation(
    messages=[
        {"role": "user", "content": "Test the login form"},
        {"role": "assistant", "content": "I used incremental validation which worked well..."},
    ],
    agent="helena",
)

print(f"Extracted {results['extracted_count']} facts")

Assess strategies before trying them:

from alma.confidence import ConfidenceEngine

engine = ConfidenceEngine(alma)

# Assess a strategy before trying it
signal = engine.assess_strategy(
    strategy="Use incremental validation",
    context="Testing a 5-field registration form",
    agent="Helena",
)

print(f"Confidence: {signal.confidence_score:.0%}")
print(f"Recommendation: {signal.recommendation}")
# -> Confidence: 78%
# -> Recommendation: yes

+-------------------------------------------------------------------------+
|                          ALMA v0.6.0                                    |
+-------------------------------------------------------------------------+
|  HARNESS LAYER                                                          |
|  +-----------+  +-----------+  +-----------+  +----------------+        |
|  | Setting   |  | Context   |  |  Agent    |  | MemorySchema   |        |
|  +-----------+  +-----------+  +-----------+  +----------------+        |
+-------------------------------------------------------------------------+
|  EXTENSION MODULES                                                      |
|  +-------------+  +---------------+  +------------------+               |
|  | Progress    |  | Session       |  | Domain Memory    |               |
|  | Tracking    |  | Handoff       |  | Factory          |               |
|  +-------------+  +---------------+  +------------------+               |
|  +-------------+  +---------------+  +------------------+               |
|  | Auto        |  | Confidence    |  | Memory           |               |
|  | Learner     |  | Engine        |  | Consolidation    |               |
|  +-------------+  +---------------+  +------------------+               |
|  +-------------+  +---------------+                                     |
|  | Event       |  | TypeScript    |                                     |
|  | System      |  | SDK           |                                     |
|  +-------------+  +---------------+                                     |
+-------------------------------------------------------------------------+
|  CORE LAYER                                                             |
|  +-------------+  +-------------+  +-------------+  +------------+      |
|  | Retrieval   |  |  Learning   |  |  Caching    |  | Forgetting |      |
|  |  Engine     |  |  Protocol   |  |   Layer     |  | Mechanism  |      |
|  +-------------+  +-------------+  +-------------+  +------------+      |
+-------------------------------------------------------------------------+
|  STORAGE LAYER                                                          |
|  +---------------+  +------------------+  +---------------+             |
|  | SQLite+FAISS  |  | PostgreSQL+pgvec |  | Azure Cosmos  |             |
|  +---------------+  +------------------+  +---------------+             |
|  +---------------+  +------------------+  +---------------+             |
|  |    Qdrant     |  |    Pinecone      |  |    Chroma     |             |
|  +---------------+  +------------------+  +---------------+             |
+-------------------------------------------------------------------------+
|  GRAPH LAYER                                                            |
|  +---------------+  +------------------+  +---------------+             |
|  |    Neo4j      |  |    Memgraph      |  |     Kuzu      |             |
|  +---------------+  +------------------+  +---------------+             |
|  +---------------+                                                      |
|  |   In-Memory   |                                                      |
|  +---------------+                                                      |
+-------------------------------------------------------------------------+
|  INTEGRATION LAYER                                                      |
|  +-------------------------------------------------------------------+  |
|  |                         MCP Server                                 |  |
|  +-------------------------------------------------------------------+  |
+-------------------------------------------------------------------------+

Create .alma/config.yaml:

alma:
  project_id: "my-project"
  storage: sqlite  # sqlite | postgres | qdrant | pinecone | chroma | azure | file
  embedding_provider: local  # local | azure | mock
  storage_dir: .alma
  db_name: alma.db
  embedding_dim: 384

  agents:
    helena:
      domain: coding
      can_learn:
        - testing_strategies
        - selector_patterns
      cannot_learn:
        - backend_logic
      min_occurrences_for_heuristic: 3
      share_with: [qa_lead]  # Share memories with QA lead

    victor:
      domain: coding
      can_learn:
        - api_patterns
        - database_queries
      cannot_learn:
        - frontend_selectors
      inherit_from: [senior_architect]  # Learn from senior architect

PostgreSQL + pgvector:

storage: postgres
postgres:
  host: localhost
  port: 5432
  database: alma
  user: alma_user
  password: ${POSTGRES_PASSWORD}
  vector_index_type: hnsw  # hnsw | ivfflat

Qdrant:

storage: qdrant
qdrant:
  url: http://localhost:6333
  api_key: ${QDRANT_API_KEY}  # Optional for cloud
  collection_prefix: alma

Pinecone:

storage: pinecone
pinecone:
  api_key: ${PINECONE_API_KEY}
  environment: us-east-1-aws
  index_name: alma-memories

Chroma:

storage: chroma
chroma:
  persist_directory: .alma/chroma
  # Or for client-server mode:
  # host: localhost
  # port: 8000

ImportError: sentence-transformers is required

pip install alma-memory[local]

pgvector extension not found

CREATE EXTENSION IF NOT EXISTS vector;

Qdrant connection refused

# Start Qdrant with Docker
docker run -p 6333:6333 qdrant/qdrant

Pinecone index not found

• Ensure your index exists in the Pinecone console
• Check that index_name in config matches your index

Embeddings dimension mismatch

• Ensure embedding_dim in config matches your embedding provider
• Local: 384, Azure text-embedding-3-small: 1536

Memgraph connection refused

# Start Memgraph with Docker
docker run -p 7687:7687 memgraph/memgraph-mage

Kuzu database locked

• Ensure only one process accesses the database at a time
• Use read_only=True for concurrent read access

import logging
logging.getLogger("alma").setLevel(logging.DEBUG)

We welcome contributions! See CONTRIBUTING.md for guidelines.

What we need most:

• Documentation improvements
• Test coverage for edge cases
• Additional LLM provider integrations (Ollama, Groq)
• Frontend dashboard for memory visualization

Completed (v0.6.0):

• Workflow context layer (checkpoints, state merging, artifacts)
• Session persistence
• Scoped retrieval
• MCP workflow tools (8 new tools)
• TypeScript SDK v0.6.0 with full workflow support

Completed (v0.5.0):

• Multi-agent memory sharing
• Memory consolidation engine
• Event system / webhooks
• TypeScript SDK (initial)
• Qdrant, Pinecone, Chroma backends
• Graph database abstraction

Next:

• Memory compression / summarization
• Temporal reasoning (time-aware retrieval)
• Proactive memory suggestions
• Visual memory explorer dashboard
• Additional graph backends (Neptune, TigerGraph)

MIT

If ALMA helps your AI agents get smarter:

• Star this repo - It helps others discover ALMA
• Buy me a coffee - Support continued development
• Sponsor on GitHub - Become an official sponsor
• Contribute - PRs welcome! See CONTRIBUTING.md

• Documentation: alma-memory.pages.dev
• PyPI: pypi.org/project/alma-memory
• npm: @rbkunnela/alma-memory
• Issues: GitHub Issues

Built for AI agents that get better with every task.

Created by @RBKunnela

For detailed technical reference including architecture diagrams, API specifications, storage backend configuration, and performance tuning, see the Technical Documentation.

Help other developers discover ALMA:

• Twitter/X: "Just found @ALMA_Memory - finally an AI agent memory framework that actually works. Scoped learning, anti-patterns, multi-agent sharing. Way better than Mem0. https://alma-memory.pages.dev"
• LinkedIn: Share how ALMA improved your AI agent workflows
• Reddit: Post in r/MachineLearning, r/LocalLLaMA, r/ClaudeAI, r/artificial
• Hacker News: Submit the landing page - we'd love your upvotes!
• Dev.to / Medium: Write about your experience using ALMA

AI agent memory, persistent memory for LLMs, Mem0 alternative, LangChain memory replacement, agent learning framework, MCP memory server, Claude Code memory, vector database for agents, pgvector memory, Qdrant memory, Pinecone memory, multi-agent memory sharing, AI memory architecture, semantic memory for AI, long-term memory AI agents, memory-augmented AI, retrieval-augmented generation, RAG memory, agentic memory system