Metadata-Version: 2.1
Name: stellar-memory
Version: 1.0.0
Summary: A celestial-structure-based AI memory management system - Give any AI human-like memory
Author: Stellar Memory Contributors
License: MIT
Project-URL: Homepage, https://sangjun0000.github.io/stellar-memory/
Project-URL: Repository, https://github.com/sangjun0000/stellar-memory
Project-URL: Documentation, https://github.com/sangjun0000/stellar-memory#readme
Project-URL: Changelog, https://github.com/sangjun0000/stellar-memory/blob/main/CHANGELOG.md
Keywords: ai,memory,llm,mcp,recall,context
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: adapters
Requires-Dist: langchain-core>=0.1.0; extra == "adapters"
Provides-Extra: ai
Requires-Dist: sentence-transformers>=2.2.0; extra == "ai"
Requires-Dist: anthropic>=0.18.0; extra == "ai"
Provides-Extra: cli
Requires-Dist: mcp[cli]>=1.2.0; extra == "cli"
Provides-Extra: connectors
Requires-Dist: httpx>=0.27.0; extra == "connectors"
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.110.0; extra == "dashboard"
Requires-Dist: uvicorn>=0.29.0; extra == "dashboard"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Provides-Extra: embedding
Requires-Dist: sentence-transformers>=2.2.0; extra == "embedding"
Provides-Extra: full
Requires-Dist: sentence-transformers>=2.2.0; extra == "full"
Requires-Dist: anthropic>=0.18.0; extra == "full"
Requires-Dist: openai>=1.0.0; extra == "full"
Requires-Dist: requests>=2.28.0; extra == "full"
Requires-Dist: mcp[cli]>=1.2.0; extra == "full"
Requires-Dist: asyncpg>=0.29.0; extra == "full"
Requires-Dist: redis>=5.0.0; extra == "full"
Requires-Dist: cryptography>=42.0.0; extra == "full"
Requires-Dist: websockets>=12.0; extra == "full"
Requires-Dist: httpx>=0.27.0; extra == "full"
Requires-Dist: fastapi>=0.110.0; extra == "full"
Requires-Dist: uvicorn>=0.29.0; extra == "full"
Requires-Dist: langchain-core>=0.1.0; extra == "full"
Provides-Extra: llm
Requires-Dist: anthropic>=0.18.0; extra == "llm"
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.2.0; extra == "mcp"
Provides-Extra: ollama
Requires-Dist: requests>=2.28.0; extra == "ollama"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29.0; extra == "postgres"
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == "redis"
Provides-Extra: security
Requires-Dist: cryptography>=42.0.0; extra == "security"
Provides-Extra: server
Requires-Dist: fastapi>=0.110.0; extra == "server"
Requires-Dist: uvicorn>=0.29.0; extra == "server"
Provides-Extra: sync
Requires-Dist: websockets>=12.0; extra == "sync"

# Stellar Memory

> Give any AI human-like memory. Built on a celestial structure.

[![PyPI](https://img.shields.io/pypi/v/stellar-memory)](https://pypi.org/project/stellar-memory/)
[![Tests](https://img.shields.io/github/actions/workflow/status/sangjun0000/stellar-memory/ci.yml?label=tests)](https://github.com/sangjun0000/stellar-memory/actions)
[![Python](https://img.shields.io/pypi/pyversions/stellar-memory)](https://pypi.org/project/stellar-memory/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

```
        Cloud (Zone 4) - Near-forgotten
       ╱                              ╲
      Belt (Zone 3) - Less important
     ╱                                ╲
    Outer (Zone 2) - Regular memories
   ╱                                    ╲
  Inner (Zone 1) - Important memories
 ╱                                        ╲
         ★ Core (Zone 0) ★
         Most important memories
         Always accessible
```

## Why Stellar Memory?

| | Traditional AI | With Stellar Memory |
|---|---|---|
| Memory | Forgets after context window | Remembers across sessions |
| Importance | Treats all info equally | Ranks by importance score |
| Organization | Flat key-value store | 5-zone celestial hierarchy |
| Forgetting | Manual deletion only | Adaptive decay, like humans |

## Quick Start

```python
from stellar_memory import StellarMemory

memory = StellarMemory()

# Store memories with different importance
memory.store("User prefers dark mode", importance=0.8)
memory.store("The weather is nice today", importance=0.2)
memory.store("Project deadline is March 1st", importance=0.9)

# Recall relevant memories
results = memory.recall("user preference")
print(results[0].content)  # "User prefers dark mode"

# Check statistics
stats = memory.stats()
print(f"Total: {stats.total_memories} memories across 5 zones")

memory.stop()
```

## Installation

```bash
# Core library (zero dependencies)
pip install stellar-memory

# With REST API server
pip install stellar-memory[server]

# With MCP server (Claude Code / Cursor)
pip install stellar-memory[mcp]

# Everything
pip install stellar-memory[full]
```

**Requirements**: Python 3.10+

## Key Features

- **5-Zone Memory Hierarchy** - Solar system model: Core, Inner, Outer, Belt, Cloud
- **Black Hole Prevention** - Logarithmic recall function prevents memory overflow
- **Emotional Memory** - 6-dimensional emotion vectors (joy, sadness, anger, fear, surprise, disgust)
- **Memory Function** - `I(m) = w₁·R(m) + w₂·F(m) + w₃·A(m) + w₄·C(m) + w₅·E(m)`
- **MCP Server** - Claude Code and Cursor integration via Model Context Protocol
- **REST API** - FastAPI with Swagger UI and ReDoc
- **Graph Analytics** - Memory relationships, communities, centrality analysis
- **Multi-Agent Sync** - CRDT-based conflict resolution + WebSocket
- **Adaptive Decay** - Human-like forgetting with reinforcement on recall
- **LangChain / OpenAI Adapters** - Drop-in integrations

## Use Cases

- **AI Chatbot** - Persistent memory across conversations
- **Personal Assistant** - Learn user preferences over time
- **Code Assistant** - Remember project context and decisions
- **Knowledge Management** - Organize and retrieve information naturally

## Four Ways to Use

### 1. Python Library

```python
from stellar_memory import StellarMemory, StellarConfig, EmotionConfig

config = StellarConfig(emotion=EmotionConfig(enabled=True))
memory = StellarMemory(config)

item = memory.store("Got promoted today!", importance=0.9)
print(f"Emotion: {item.emotion.dominant}")  # "joy"
```

### 2. REST API

```bash
stellar-memory serve-api
# Open http://localhost:9000/docs for Swagger UI
```

```bash
curl -X POST http://localhost:9000/api/v1/store \
  -H "Content-Type: application/json" \
  -d '{"content": "Remember this", "importance": 0.7}'
```

### 3. MCP Server (Claude Code / Cursor)

```bash
stellar-memory init-mcp --ide claude
# Restart Claude Desktop - memory tools are now available
```

### 4. Docker

```bash
docker-compose up stellar
# API available at http://localhost:9000
```

## Architecture

The memory function determines where each memory lives:

```
I(m) = w₁·R(m) + w₂·F(m) + w₃·A(m) + w₄·C(m) + w₅·E(m)

R(m) = log(1 + recall_count)     # Recall (log-bounded)
F(m) = -α · time_since_recall    # Freshness (decays, resets on recall)
A(m) = ai_evaluated_importance   # Arbitrary importance (AI-judged)
C(m) = connection_strength       # Graph connectivity
E(m) = emotional_intensity       # Emotion weight
```

Memories are periodically **reorbited** - moved between zones based on their total score. High-scoring memories migrate toward the Core; low-scoring ones drift to the Cloud and eventually evaporate.

## Documentation

- [Getting Started](https://github.com/sangjun0000/stellar-memory/blob/main/docs/getting-started/)
- [API Reference](https://github.com/sangjun0000/stellar-memory/blob/main/docs/api-reference/)
- [REST API](https://github.com/sangjun0000/stellar-memory/blob/main/docs/rest-api/)
- [MCP Integration](https://github.com/sangjun0000/stellar-memory/blob/main/docs/mcp/claude-code/)
- [Guides](https://github.com/sangjun0000/stellar-memory/blob/main/docs/guides/chatbot/)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.
