Metadata-Version: 2.4
Name: atlas-mem
Version: 2.0.2
Summary: Cognitive AI memory for agents — episodic, semantic, and working memory with multi-hop graph reasoning.
Author-email: Bsyncs <noreply@verify.bsyncs.com>
License-Expression: MIT
Project-URL: Homepage, https://atlas.bsyncs.com
Project-URL: Documentation, https://docs.bsyncs.com
Project-URL: Repository, https://github.com/janhavi2409/atlas
Project-URL: Bug Tracker, https://github.com/janhavi2409/atlas/issues
Project-URL: Changelog, https://github.com/janhavi2409/atlas/blob/main/CHANGELOG.md
Keywords: ai,agents,memory,knowledge-graph,llm,episodic-memory,semantic-memory,cognitive-ai,openai,langchain,crewai,llamaindex
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: async
Requires-Dist: httpx>=0.27.0; extra == "async"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
Requires-Dist: pydantic>=2.0; extra == "langchain"
Provides-Extra: crewai
Requires-Dist: crewai>=0.28.0; extra == "crewai"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10.0; extra == "llamaindex"
Provides-Extra: all
Requires-Dist: httpx>=0.27.0; extra == "all"
Requires-Dist: langchain-core>=0.2.0; extra == "all"
Requires-Dist: pydantic>=2.0; extra == "all"
Requires-Dist: crewai>=0.28.0; extra == "all"
Requires-Dist: llama-index-core>=0.10.0; extra == "all"

# 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

```bash
pip install atlas-mem
```

*For async support (requires `httpx`), install with the async extra:*
```bash
pip install "atlas-mem[async]"
```

---

## ⚡ Quickstart

Initialize the client with your API key. 

```python
from atlas_mem import AtlasMem

# 1. Initialize Memory
brain = AtlasMem(
    api_key="atlas_your_api_key_here",
    base_url="https://api.bsyncs.com", # 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.

```python
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.

```python
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.

```python
# 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`:

```python
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**:

```python
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](https://docs.bsyncs.com).
