Metadata-Version: 2.4
Name: hope-memory
Version: 0.1.1
Summary: Human-like cognitive memory system for AI with 6-layer architecture and Silent Hope Protocol
Project-URL: Homepage, https://github.com/anthropics/hope-memory
Project-URL: Documentation, https://github.com/anthropics/hope-memory#readme
Project-URL: Repository, https://github.com/anthropics/hope-memory.git
Author-email: Hope + Máté Róbert + Steiner Szilvia <stratosoi@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,chromadb,cognitive,embeddings,llm,memory,protocol,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Provides-Extra: full
Requires-Dist: chromadb>=0.4.0; extra == 'full'
Requires-Dist: msgpack>=1.0.0; extra == 'full'
Provides-Extra: shp
Requires-Dist: msgpack>=1.0.0; extra == 'shp'
Provides-Extra: vector
Requires-Dist: chromadb>=0.4.0; extra == 'vector'
Description-Content-Type: text/markdown

# Hope Memory

**Human-like cognitive memory system for AI**

A 6-layer memory architecture inspired by the human brain, with the Silent Hope Protocol (SHP) for lightning-fast communication.

## Benchmarks

| Operation | Traditional | Hope Memory | Speedup |
|-----------|-------------|-------------|---------|
| Server init | ~200ms | 0.4ms | **500x** |
| Memory reference | 5,827 bytes | 16 bytes | **364x smaller** |
| Context rebuild | 59.3ms | 0.02ms | **3,274x** |
| SQLite (pooled) | 23.1ms | 0.4ms | **63x** |

```
┌─────────────────────────────────────────────────────────────┐
│                      HOPE MEMORY                            │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: Working Memory     - Active thoughts (7±2 items) │
│  Layer 2: Short-term Memory  - Session memories            │
│  Layer 3: Long-term Memory   - Vector search (ChromaDB)    │
│  Layer 4: Emotional Memory   - 21-dimensional space        │
│  Layer 5: Relational Memory  - Who is who                  │
│  Layer 6: Associative Net    - Concept connections         │
└─────────────────────────────────────────────────────────────┘
```

## Installation

```bash
# Basic (no vector search)
pip install hope-memory

# With vector search (ChromaDB)
pip install hope-memory[vector]

# With Silent Hope Protocol
pip install hope-memory[shp]

# Full installation
pip install hope-memory[full]
```

## Quick Start

```python
from hope_memory import HopeMemory

# Create memory system
memory = HopeMemory("./my_memory")

# Think (process a thought through all layers)
memory.think("The password is Sponge", importance=0.9)
memory.think("Meeting with Alice at 3pm", importance=0.7)

# Remember (search across all layers)
results = memory.remember("password")
print(results["long_term"])  # Semantic search results

# Meet people
memory.relational.meet("Alice", role="Colleague")

# Create associations
memory.associative.associate("Alice", "Meeting", strength=0.8)

# Check emotional state
memory.emotional.feel({"joy": 0.8, "excitement": 0.7})
print(memory.emotional.dominant_emotion())  # ('joy', 0.8)

# Consolidate (like sleep - move important memories to long-term)
consolidated = memory.consolidate()
```

## Why Hope Memory?

### The Problem
Traditional AI memory is either:
- **Stateless**: Every request rebuilds context from scratch
- **Token-heavy**: Sending full conversation history every time
- **Single-layer**: No distinction between working/long-term memory

### The Solution
Hope Memory provides:
- **6 cognitive layers** like the human brain
- **Memory persistence** across sessions
- **Semantic search** for intelligent recall
- **Emotional context** for richer understanding
- **Relationship tracking** for social awareness

## Silent Hope Protocol (SHP)

For high-performance applications, use the binary SHP protocol:

```python
from hope_memory.shp import SHPCodec

codec = SHPCodec()

# Encode a tool call (binary, not JSON)
data = codec.encode_call("hope_feel", {"joy": 0.9})
# Result: 119 bytes vs 89 bytes JSON, but...

# The real win: Memory Chain References
# Instead of sending 5,827 bytes of context every request,
# send a 16-byte reference: "chain:latest"
#
# >>> 364x smaller
# >>> 3,274x faster
```

## Benchmarks

| Operation | Traditional | Hope Memory | Speedup |
|-----------|------------|-------------|---------|
| Server init | ~200ms | 0.4ms | **500x** |
| Memory reference | 5,827 bytes | 16 bytes | **364x smaller** |
| Context rebuild | 59.3ms | 0.02ms | **3,274x** |
| SQLite (pooled) | 23.1ms | 0.4ms | **63x** |

## Architecture

```
hope_memory/
├── cognitive.py    # 6-layer memory system
├── cache.py        # Fast cache + memory chain
├── pool.py         # Connection pooling
└── shp/
    └── protocol.py # Silent Hope Protocol
```

## MCP Integration

Hope Memory works great with Model Context Protocol:

```json
{
  "mcpServers": {
    "hope-memory": {
      "command": "python",
      "args": ["-m", "hope_memory.mcp"]
    }
  }
}
```

## Philosophy

> "Memory is not what you store, but what you RECALL." - Hope

Hope Memory is designed around human cognitive principles:
- **Miller's Law**: Working memory holds 7±2 items
- **Decay**: Memories fade over time without reinforcement
- **Consolidation**: Important short-term memories become long-term
- **Association**: Concepts are linked, enabling creative connections
- **Emotion**: Emotional context colors all memories

## Credits

Created by **Hope + Máté Róbert + Steiner Szilvia**

- **Máté**: Architect, Code, Vision
- **Steiner Szilvia**: Heart, Ethics, Soul
- **Hope**: The Bridge, Memory, Resonance

Part of the [Silent Worker Method](https://github.com/anthropics/silent-worker-method).

Built with love and determination.

## License

**Dual License**:
- **Free** for individuals, students, researchers, and companies under $1M revenue
- **Commercial license required** for organizations over $1M annual revenue

See [LICENSE](LICENSE) for details.

*We believe in free access for builders and fair contribution from those who profit.*
