neuromem-sdk 0.1.0

Brain-Inspired Memory SDK for LangChain & LangGraph Agents

NeuroMem SDK

Brain-Inspired Memory System for LangChain & LangGraph Agents

⚠️ Alpha Release: This is an early alpha version (v0.1.0). APIs may change. Not recommended for production use yet.

NeuroMem SDK provides a human-inspired, multi-layer memory system that enables LLM agents to:

• 🧠 Remember experiences (episodic memory)
• 📚 Learn stable facts (semantic memory)
• 🎯 Adapt behavior (procedural memory)
• 🔄 Forget and correct over time
• 🎪 Retrieve contextually based on goals, salience, and recency

---

🚀 Quick Start

Installation

# Basic installation
pip install neuromem-sdk

# With all optional dependencies
pip install neuromem-sdk[all]

# Framework-specific installations
pip install neuromem-sdk[langchain]   # LangChain integration
pip install neuromem-sdk[langgraph]   # LangGraph integration
pip install neuromem-sdk[postgres]    # PostgreSQL backend
pip install neuromem-sdk[qdrant]      # Qdrant vector store

Basic Usage

from neuromem import NeuroMem

# Create memory system
memory = NeuroMem.for_langchain(user_id="user_123")

# Observe interactions
memory.observe(
    user_input="I prefer concise answers",
    assistant_output="Got it! I'll keep responses brief."
)

# Retrieve relevant memories
context = memory.retrieve(
    query="How should I format my responses?",
    k=5
)

# Access memory content
for item in context:
    print(f"{item.memory_type}: {item.content}")

---

📖 Table of Contents

• Features
• Architecture
• Installation
• Configuration
• Framework Integrations
  • LangChain
  • LangGraph
  • LiteLLM
• Storage Backends
• Advanced Features
• API Reference
• Performance
• Security
• Troubleshooting
• Contributing
• License

---

✨ Features

Core Memory Systems

• Episodic Memory: Recent experiences and interactions
• Semantic Memory: Stable facts and knowledge
• Procedural Memory: Behavioral patterns and preferences
• Session Memory: Temporary in-conversation context

Brain-Inspired Retrieval

• Multi-factor scoring: Similarity + salience + recency + reinforcement
• Hybrid retrieval: Combines multiple memory types intelligently
• Competitive inhibition: Prevents near-duplicate memories
• Confidence filtering: Only retrieves reliable memories

Production-Ready Features

• ⚡ Async workers: Non-blocking memory operations (<100ms latency)
• 🔄 Retry logic: Exponential backoff with circuit breakers
• 💾 Embedding cache: Reduces API costs by 80%
• 🛡️ Input validation: Prevents SQL injection and malicious inputs
• 📊 Structured logging: JSON logging with PII redaction
• 🎯 Rate limiting: Handles OpenAI API limits gracefully

Memory Consolidation

• LLM-powered: Extracts facts and patterns automatically
• Forgetting curve: Memories decay naturally over time
• Reconsolidation: Memories strengthen when accessed

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    NeuroMem SDK                          │
│                                                           │
│  ┌─────────────┐     ┌──────────────┐   ┌─────────────┐│
│  │  Episodic   │────▶│   Memory     │◀──│  Semantic   ││
│  │   Memory    │     │  Controller  │   │   Memory    ││
│  └─────────────┘     └──────────────┘   └─────────────┘│
│         │                   │                   │        │
│         │            ┌──────┴──────┐            │        │
│         │            │  Retrieval   │            │        │
│         └───────────▶│   Engine     │◀───────────┘        │
│                      └──────────────┘                     │
│                             │                              │
│                      ┌──────┴──────┐                      │
│                      │   Storage    │                      │
│                      │   Backend    │                      │
│                      └──────┬───────┘                      │
│                             │                              │
└─────────────────────────────┼──────────────────────────────┘
                              │
                    ┌─────────┴──────────┐
                    │                    │
            ┌───────▼─────┐      ┌──────▼──────┐
            │  PostgreSQL │      │   Qdrant    │
            │  + pgvector │      │  (vectors)  │
            └─────────────┘      └─────────────┘

---

🔧 Installation

Prerequisites

• Python 3.9 or higher
• OpenAI API key (for embeddings)
• Optional: PostgreSQL with pgvector extension

Install from PyPI

pip install neuromem-sdk

Install from Source

git clone https://github.com/neuromem/neuromem-sdk.git
cd neuromem-sdk
pip install -e .

Verify Installation

python test_setup.py

---

⚙️ Configuration

Create a neuromem.yaml file:

neuromem:
  model:
    embedding: text-embedding-3-large
    consolidation_llm: gpt-4o-mini

  storage:
    database:
      type: memory  # Options: postgres, sqlite, memory, qdrant
      # url: postgresql://user:pass@localhost/neuromem  # For postgres

  memory:
    decay_enabled: true
    consolidation_interval: 10  # Consolidate every N turns
    max_active_memories: 50
    episodic_retention_days: 30

  retrieval:
    hybrid_enabled: true
    recency_weight: 0.2
    importance_weight: 0.3
    similarity_weight: 0.5

  async:
    enabled: true
    critical_queue_size: 1000

Environment Variables

# Required
export OPENAI_API_KEY=sk-...

# Optional
export NEUROMEM_CACHE_EMBEDDINGS=true  # Enable embedding cache (default: true)

---

🔌 Framework Integrations

LangChain Integration

from neuromem import NeuroMem
from neuromem.adapters.langchain import add_memory
from langchain.chains import LLMChain
from langchain.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

# Create memory
memory = NeuroMem.for_langchain(user_id="user_123")

# Create chain
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant. Context: {context}"),
    ("human", "{input}")
])
llm = ChatOpenAI(model="gpt-4")
chain = prompt | llm

# Add memory to chain
chain_with_memory = add_memory(chain, memory)

# Use chain
response = chain_with_memory.invoke({"input": "What are my preferences?"})

LangGraph Integration

from neuromem import NeuroMem
from neuromem.adapters.langgraph import with_memory
from langgraph.graph import StateGraph

# Create memory
memory = NeuroMem.for_langgraph(user_id="user_123")

# Create graph
graph = StateGraph(...)
# ... define graph nodes and edges ...

# Compile with memory
app = with_memory(graph.compile(), memory)

# Run
result = app.invoke({"input": "Hello"})

LiteLLM Integration

from neuromem import NeuroMem
from neuromem.adapters.litellm import completion_with_memory

# Create memory
memory = NeuroMem.for_litellm(user_id="user_123")

# Make completion with memory
response = completion_with_memory(
    model="gpt-4",
    messages=[{"role": "user", "content": "What do I like?"}],
    memory=memory
)

---

💾 Storage Backends

In-Memory (Default)

storage:
  database:
    type: memory

Fast, but data lost on restart. Good for development.

PostgreSQL + pgvector

storage:
  database:
    type: postgres
    url: postgresql://user:pass@localhost:5432/neuromem

Setup:

CREATE DATABASE neuromem;
CREATE EXTENSION vector;

SQLite

storage:
  database:
    type: sqlite
    url: neuromem.db

Lightweight, file-based storage.

Qdrant

storage:
  vector_store:
    type: qdrant
    config:
      host: localhost
      port: 6333
      collection_name: neuromem

High-performance vector search.

---

🚀 Advanced Features

Manual Consolidation

# Trigger consolidation manually
memory.consolidate()

Memory Management

# List all memories
memories = memory.list(memory_type="semantic", limit=50)

# Update a memory
memory.update(memory_id="...", content="Updated content")

# Delete a memory
memory.forget(memory_id="...")

# Explain why a memory was retrieved
explanation = memory.explain(memory_id="...")
print(explanation)

Health Checks

# Check system health
from neuromem.health import get_health_status

health = get_health_status(memory)
print(health)
# {'status': 'healthy', 'database': 'connected', 'workers': {...}}

Cache Management

from neuromem.utils.embeddings import get_cache_stats, clear_embedding_cache

# Get cache statistics
stats = get_cache_stats()
print(f"Cache size: {stats['size']}/{stats['max_size']}")

# Clear cache
clear_embedding_cache()

---

📊 API Reference

NeuroMem Class

NeuroMem.from_config(config_path, user_id)

Initialize from configuration file.

NeuroMem.for_langchain(user_id, config_path="neuromem.yaml")

Quick initialization for LangChain.

NeuroMem.for_langgraph(user_id, config_path="neuromem.yaml")

Quick initialization for LangGraph.

NeuroMem.for_litellm(user_id, config_path="neuromem.yaml")

Quick initialization for LiteLLM.

retrieve(query, task_type="chat", k=8)

Retrieve relevant memories.

observe(user_input, assistant_output)

Record a user-assistant interaction.

consolidate()

Trigger memory consolidation.

list(memory_type=None, limit=50)

List memories.

explain(memory_id)

Explain memory retrieval.

update(memory_id, content)

Update memory content.

forget(memory_id)

Delete a memory.

close()

Close and release resources.

---

⚡ Performance

Benchmarks

Operation	Latency	Notes
observe()	<100ms	Async mode (queued)
retrieve()	200-500ms	Depends on storage backend
consolidate()	2-10s	Background, non-blocking

Optimization Tips

1. Enable caching: Reduces OpenAI API costs by 80%

   export NEUROMEM_CACHE_EMBEDDINGS=true
   

2. Use PostgreSQL with pgvector: 3-5x faster than in-memory for large datasets

3. Batch operations: Use batch_get_embeddings() for multiple texts

4. Tune queue sizes: Adjust in neuromem.yaml:

   async:
     critical_queue_size: 1000
     high_queue_size: 500
   

---

🛡️ Security

Input Validation

All user inputs are validated:

• User IDs must be valid UUIDs
• Content length limited to 50KB
• SQL injection prevention via filter validation

API Key Security

# Store API keys securely
export OPENAI_API_KEY=sk-...

# Never commit keys to git
echo ".env" >> .gitignore

PII Redaction

Structured logging automatically redacts:

• Email addresses
• Phone numbers
• Social Security Numbers
• Credit card numbers

---

🐛 Troubleshooting

Common Issues

OpenAI API Rate Limits

Error: RateLimitError: You exceeded your current quota

Solution: The SDK includes automatic retry logic with exponential backoff. If you still hit limits:

# Reduce concurrent operations
memory.config.async.critical_queue_size = 100

# Enable aggressive caching
export NEUROMEM_CACHE_EMBEDDINGS=true

Memory Growth

Issue: Database size growing too large

Solution:

1. Enable memory decay:

   memory:
     decay_enabled: true
     episodic_retention_days: 30
   

2. Run manual cleanup:

   memory.consolidate()  # Promotes important memories, forgets old ones
   

Slow Retrieval

Issue: retrieve() takes >1 second

Solutions:

1. Add database indexes (PostgreSQL):

   CREATE INDEX idx_memory_embedding ON user_memories
   USING ivfflat (embedding vector_cosine_ops);
   

2. Reduce k parameter:

   memory.retrieve(query, k=5)  # Instead of k=50
   

Enable Debug Logging

from neuromem.utils.logging import get_logger
import logging

logger = get_logger(__name__, level=logging.DEBUG)

---

🧪 Testing

Run the test suite:

# Basic tests
bash test_sdk.sh

# Full setup verification
python test_setup.py

---

📈 Roadmap

v0.1.0 (Alpha) - Current Release

• Basic memory types (Episodic, Semantic)
• Retrieval engine
• Storage backends (Memory, SQLite, Postgres, Qdrant)

v0.1.0 (Beta) - Target: Q2 2026

• Unit test coverage >80%
• Performance optimization (parallel retrieval)
• Comprehensive documentation
• Load testing (10,000+ users)

v1.0.0 (Production) - Target: Q3 2026

• Security audit
• Multi-tenancy support
• Advanced analytics dashboard
• Enterprise features

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone repo
git clone https://github.com/neuromem/neuromem-sdk.git
cd neuromem-sdk

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -e .[dev]

# Run tests
bash test_sdk.sh

---

📜 License

MIT License - see LICENSE for details.

---

🙏 Acknowledgments

• Inspired by cognitive neuroscience research on human memory
• Built on top of LangChain, LangGraph, and OpenAI
• Thanks to all contributors!

---

📞 Support

• Issues: GitHub Issues
• Documentation: docs.neuromem.ai
• Discussions: GitHub Discussions

---

Made with ❤️ by the NeuroMem Team