Metadata-Version: 2.4
Name: shodh-memory
Version: 0.1.80
Summary: Cognitive memory system for AI agents - biological memory processing in a single binary
Home-page: https://github.com/varun29ankuS/shodh-memory
Author: Shodh Team
Author-email: 29.varuns@gmail.com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10.0; extra == "llamaindex"
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.0.7; extra == "openai-agents"
Requires-Dist: pydantic>=2.0.0; extra == "openai-agents"
Provides-Extra: all
Requires-Dist: langchain-core>=0.2.0; extra == "all"
Requires-Dist: llama-index-core>=0.10.0; extra == "all"
Requires-Dist: openai-agents>=0.0.7; extra == "all"
Requires-Dist: pydantic>=2.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<p align="center">
  <img src="https://raw.githubusercontent.com/varun29ankuS/shodh-memory/main/assets/logo.png" width="120" alt="Shodh-Memory">
</p>

<h1 align="center">Shodh-Memory</h1>

<p align="center">
  <a href="https://registry.modelcontextprotocol.io/servers/io.github.varun29ankuS/shodh-memory"><img src="https://img.shields.io/badge/MCP-Registry-green" alt="MCP Registry"></a>
  <a href="https://www.npmjs.com/package/@shodh/memory-mcp"><img src="https://img.shields.io/npm/v/@shodh/memory-mcp.svg?logo=npm" alt="npm"></a>
  <a href="https://pypi.org/project/shodh-memory/"><img src="https://img.shields.io/pypi/v/shodh-memory.svg" alt="PyPI"></a>
  <a href="https://pepy.tech/project/shodh-memory"><img src="https://static.pepy.tech/badge/shodh-memory" alt="Downloads"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"></a>
</p>

---

<p align="center"><i>Memory that learns. Single binary. Runs offline.</i></p>

---

We built this because AI agents forget everything between sessions. They make the same mistakes, ask the same questions, lose context constantly.

Shodh-Memory fixes that. It's a cognitive memory systemâ€”Hebbian learning, activation decay, semantic consolidationâ€”packed into a single 8MB binary that runs offline.

**How it works:**

Experiences flow through three tiers based on Cowan's working memory model<br>
[1]. New information enters capacity-limited working memory, overflows into session storage, and consolidates into long-term memory based on importance. When memories are retrieved together successfully, their connections strengthenâ€”classic Hebbian learning<br>
[2]. After enough co-activations, those connections become permanent. Unused memories naturally fade. The system learns what matters to *you*.

**What you get:**

Your decisions, errors, and patternsâ€”searchable and private. No cloud. No API keys. Your memory, your machine.

```
Working Memory â”€â”€overflowâ”€â”€â–¶ Session Memory â”€â”€importanceâ”€â”€â–¶ Long-Term Memory
   (100 items)                  (500 MB)                      (RocksDB)
```

### Architecture

**Storage & Retrieval**

- Vamana graph index for approximate nearest neighbor search [3]
- MiniLM-L6 embeddings (384-dim) for semantic similarity
- RocksDB for durable persistence across restarts
- User isolation â€” each agent gets independent memory space

**Cognitive Processing**

- *Activation decay* â€” exponential decay A(t) = Aâ‚€ Â· e^(-Î»t) applied each maintenance cycle (Î» configurable)
- *Hebbian strengthening* â€” co-retrieved memories form graph edges; edge weight w increases as w' = w + Î±(1 - w) on each co-activation
- *Long-term potentiation* â€” edges surviving threshold co-activations (default: 5) become permanent, exempt from decay
- *Importance scoring* â€” composite score from memory type, content length, entity density, technical terms, access frequency

**Semantic Consolidation**

- Episodic memories older than 7 days compress into semantic facts
- Entity extraction preserves key information during compression
- Original experiences archived, compressed form used for retrieval

**Context Bootstrapping**

- `context_summary()` provides categorized session context on startup
- Returns decisions, learnings, patterns, errors â€” structured for LLM consumption
- `brain_state()` exposes full 3-tier visualization data

### Use cases

**Local LLM memory** â€” Give Claude, GPT, or any local model persistent memory across sessions. Remember user preferences, past decisions, learned patterns.

**Robotics & drones** â€” On-device experience accumulation. A robot that remembers which actions worked, which failed, without cloud round-trips.

**Edge AI** â€” Run on Jetson, Raspberry Pi, industrial PCs. Sub-millisecond retrieval, zero network dependency.

**Personal knowledge base** â€” Your own searchable memory. Decisions, learnings, discoveriesâ€”private and local.

### Compared to alternatives

| | Shodh-Memory | Mem0 | Cognee |
|---|---|---|---|
| **Deployment** | Single 8MB binary | Cloud API | Neo4j + Vector DB |
| **Offline** | 100% | No | Partial |
| **Learning** | Hebbian + decay + LTP | Vector similarity | Knowledge graphs |
| **Latency** | Sub-millisecond | Network-bound | Database-bound |
| **Best for** | Local-first, edge, privacy | Cloud scale | Enterprise ETL |

### Installation

**Claude Code / Claude Desktop:**

Add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "shodh-memory": {
      "command": "npx",
      "args": ["-y", "@shodh/memory-mcp"]
    }
  }
}
```

Config file locations:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**Python:**
```
pip install shodh-memory

# With LangChain support
pip install shodh-memory[langchain]

# With LlamaIndex support
pip install shodh-memory[llamaindex]

# All integrations
pip install shodh-memory[all]
```

**From source:**
```
cargo build --release
./target/release/shodh-memory-server
```

### Usage

**Python**

```python
from shodh_memory import Memory

memory = Memory(user_id="my-agent")

# Store
memory.remember("User prefers dark mode", memory_type="Decision")
memory.remember("JWT tokens expire after 24h", memory_type="Learning")

# Search
results = memory.recall("user preferences", limit=5)

# Session bootstrap - get categorized context
summary = memory.context_summary()
# Returns: decisions, learnings, patterns, errors
```

**LangChain**

```python
from langchain.chains import ConversationChain
from langchain_openai import ChatOpenAI
from shodh_memory.integrations.langchain import ShodhMemory

memory = ShodhMemory(
    server_url="http://localhost:3030",
    user_id="agent-1",
    api_key="your-key"
)

chain = ConversationChain(llm=ChatOpenAI(), memory=memory)
response = chain.invoke({"input": "Hello!"})

# Memory is automatically loaded/saved per interaction
# Sub-millisecond retrieval, no LLM calls for memory ops
```

**LlamaIndex**

```python
from shodh_memory.integrations.llamaindex import ShodhLlamaMemory

memory = ShodhLlamaMemory(
    server_url="http://localhost:3030",
    user_id="agent-1",
    api_key="your-key"
)

# Store memories
memory.put("User prefers Python", memory_type="Decision")

# Retrieve by semantic search
results = memory.get("programming preferences")

# Get formatted context for prompts
context = memory.get_context("current task query")
```

**ChatGPT (Custom GPT Actions)**

Use the OpenAPI spec at `/openapi.yaml` to create a Custom GPT with memory:

1. Create a Custom GPT at https://chat.openai.com/gpts/editor
2. Add an Action with the OpenAPI spec from your server
3. The GPT can now store and recall memories across sessions

**REST API**

```
# Store
curl -X POST http://localhost:3030/api/record \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "user_id": "agent-1",
    "experience": {
      "content": "Deployment requires Docker 24+",
      "experience_type": "Learning"
    }
  }'

# Search
curl -X POST http://localhost:3030/api/recall \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"user_id": "agent-1", "query": "deployment requirements", "limit": 5}'
```

### Memory types

Different types get different importance weights in the scoring model:

- **Decision** (+0.30) â€” choices, preferences, conclusions
- **Learning** (+0.25) â€” new knowledge, facts learned
- **Error** (+0.25) â€” mistakes, things to avoid
- **Discovery**, **Pattern** (+0.20) â€” findings, recurring behaviors
- **Task** (+0.15) â€” work items
- **Context**, **Observation** (+0.10) â€” general info

Importance also increases with: content length, entity density, technical terms, and access frequency.

### API reference

**Python client**

| Method | What it does |
|--------|--------------|
| `remember(content, memory_type, tags)` | Store a memory |
| `recall(query, limit)` | Semantic search |
| `context_summary()` | Categorized context for session start |
| `brain_state()` | 3-tier visualization data |
| `stats()` | Memory statistics |
| `delete(memory_id)` | Remove a memory |

**REST endpoints**

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/remember` | POST | Store memory |
| `/api/recall` | POST | Semantic search |
| `/api/memories` | POST | List memories |
| `/api/memory/{id}` | GET/DELETE | Single memory operations |
| `/api/users/{id}/stats` | GET | User statistics |
| `/api/brain/{user_id}` | GET | 3-tier state |
| `/health` | GET | Health check |

### Configuration

```
SHODH_PORT=3030                    # Default: 3030
SHODH_MEMORY_PATH=./data           # Default: ./shodh_memory_data
SHODH_API_KEYS=key1,key2           # Required in production
SHODH_MAINTENANCE_INTERVAL=300     # Decay cycle (seconds)
SHODH_ACTIVATION_DECAY=0.95        # Decay factor per cycle
```

### Platform support

| Platform | Status | Use case |
|----------|--------|----------|
| Linux x86_64 | âœ“ | Servers, workstations |
| macOS ARM64 | âœ“ | Development (Apple Silicon) |
| Windows x86_64 | âœ“ | Development, industrial PCs |
| Linux ARM64 | Coming soon | Jetson, Raspberry Pi, drones |

### References

[1] Cowan, N. (2010). The Magical Mystery Four: How is Working Memory Capacity Limited, and Why? *Current Directions in Psychological Science*, 19(1), 51-57. https://pmc.ncbi.nlm.nih.gov/articles/PMC4207727/

[2] Magee, J.C., & Grienberger, C. (2020). Synaptic Plasticity Forms and Functions. *Annual Review of Neuroscience*, 43, 95-117. https://pmc.ncbi.nlm.nih.gov/articles/PMC10410470/

[3] Subramanya, S.J., et al. (2019). DiskANN: Fast Accurate Billion-point Nearest Neighbor Search on a Single Node. *NeurIPS 2019*. https://papers.nips.cc/paper/9527-diskann-fast-accurate-billion-point-nearest-neighbor-search-on-a-single-node

[4] Dudai, Y., Karni, A., & Born, J. (2015). The Consolidation and Transformation of Memory. *Neuron*, 88(1), 20-32. https://pmc.ncbi.nlm.nih.gov/articles/PMC4183265/

### License

Apache 2.0

---

[MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.varun29ankuS/shodh-memory) Â· [PyPI](https://pypi.org/project/shodh-memory/) Â· [npm](https://www.npmjs.com/package/@shodh/memory-mcp) Â· [GitHub](https://github.com/varun29ankuS/shodh-memory)
