atlas-mem 2.0.1

Cognitive AI memory for agents — episodic, semantic, and working memory with multi-hop graph reasoning.

AtlasMem: Cognitive AI Memory SDK

AtlasMem is the official Python SDK for the Bsyncs Atlas Cognitive Brain service (CAB-QA). It equips your LLM agents with long-term, query-adaptive Episodic, Semantic (Knowledge Graph), and Working Memory.

Designed to be lightweight and zero-dependency (only requests needed), it works seamlessly with OpenAI, LangChain, CrewAI, LlamaIndex, and plain Python applications.

---

🚀 Installation

pip install atlas-mem

For async support (requires httpx), install with the async extra:

pip install "atlas-mem[async]"

---

⚡ Quickstart

Initialize the client with your API key. By default, it connects to your local Atlas instance on port 8000.

from atlas_mem import AtlasMem

# 1. Initialize Memory
brain = AtlasMem(
    api_key="atlas_your_api_key_here",
    base_url="http://localhost:8000", # Point to your NGINX router or SaaS URL
    user_id="user-123",               # Isolate memories per user
    session_id="session-abc"          # Optional: sliding working memory window
)

# 2. Ingest Facts (Automatically extracts Graph Nodes, Edges, and Vector Chunks)
brain.add("Sarah Jenkins is the Lead Software Engineer at Acme Corp.")
brain.add("Acme Corp's primary database was recently migrated to PostgreSQL.")

# 3. Retrieve Context (Hybrid Search across Graph + Vector DBs)
results = brain.search("Who is Sarah and what database does her company use?")

# 4. Format for your LLM System Prompt
print(results.format())

---

🧠 Advanced Features

📦 Batch Ingestion

When you have a lot of historical context to inject at once, use add_batch to process it efficiently.

brain.add_batch([
    "Alex prefers Python over Java.",
    "The frontend is built with React and Vite.",
    "Deployment happens automatically via GitHub Actions."
])

🕸️ Natural Language Graph QA

Query your knowledge graph directly using natural language. The CAB-QA engine will translate the question into a multi-hop Cypher query, traverse the graph, and return a grounded answer.

answer = brain.ask("How many hops are there between Sarah Jenkins and the PostgreSQL database?")
print(answer)

🧹 Memory Lifecycle Management

Keep your AI's memory clean, highly relevant, and performant. Atlas supports Ebbinghaus temporal decay, cluster compression, and pruning.

# View current graph schema
print(brain.get_schema())

# Dry-run pruning to see how many low-relevance nodes would be deleted
prune_status = brain.prune(threshold=0.1, dry_run=True)
print(f"Candidates for pruning: {prune_status['candidates']}")

# Run full memory consolidation (decays older memories & compresses clusters)
brain.consolidate(force=True)

# View memory stats (Entity count, relation count, etc.)
print(brain.stats())

---

⏱️ Async Usage

If you are running inside an asynchronous framework like FastAPI, LangGraph, or Discord.py, use AsyncAtlasMem:

import asyncio
from atlas_mem import AsyncAtlasMem

async def main():
    # Use as an async context manager
    async with AsyncAtlasMem(api_key="atlas_...", user_id="user-123") as brain:
        
        await brain.add("We decided to use AWS RDS for production.")
        
        results = await brain.search("Where is production hosted?")
        print(results.format())

if __name__ == "__main__":
    asyncio.run(main())

---

🤖 Agent Framework Integrations

AtlasMem is designed to be injected directly into modern agent frameworks as custom tools. Here is how you can easily wrap it for LangChain:

from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI
from langchain_core.tools import Tool
from atlas_mem import AtlasMem

# 1. Init Brain
brain = AtlasMem(api_key="atlas_...", user_id="user-123")

# 2. Wrap as LangChain Tools
tools = [
    Tool(
        name="atlas_save_memory",
        func=lambda text: brain.add(text).msg,
        description="Save important facts, decisions, or context to long-term memory."
    ),
    Tool(
        name="atlas_search_memory",
        func=lambda query: brain.search(query).format(),
        description="Search long-term memory for relevant context before answering."
    ),
    Tool(
        name="atlas_graph_qa",
        func=lambda q: brain.ask(q),
        description="Answer complex relational questions using knowledge graph reasoning."
    )
]

# 3. Give to Agent
llm = ChatOpenAI(temperature=0)
agent = initialize_agent(tools, llm, agent=AgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION)

agent.run("Remember that my favorite programming language is Python.")

---

📚 API Reference Overview

AtlasMem & AsyncAtlasMem

Method	Description
.add(text, source="user")	Extracts entities/relations and stores them in memory.
.add_batch(texts)	Ingests a list of strings efficiently.
.search(query, k=5)	Performs hybrid search returning relevant memory facts.
.ask(question, max_hops=3)	Performs multi-hop Graph QA, returning a direct answer.
.consolidate(force=False)	Runs the lifecycle engine (decay, compress, prune).
.prune(threshold, dry_run)	Removes low-confidence memories.
.get_schema()	Returns the current Neo4j ontology/schema as a string.
.stats()	Returns counts of current episodic chunks and semantic relations.
.health()	Pings the backing databases to ensure the service is online.

---

💡 Support

For detailed documentation, architectural overviews, and support, visit docs.bsyncs.com.