---
name: shodh-memory
description: Persistent cognitive memory for AI agents. Use when user wants to remember context across conversations, recall past decisions, or store learnings.
---

# Shodh Memory

Persistent memory for AI agents - memories persist across sessions and can be recalled semantically.

## Overview

Shodh Memory provides:
- **Persistent Context** - Memories survive across Claude Code sessions
- **Semantic Search** - Find memories by meaning, not just keywords  
- **Auto-Learning** - Frequently accessed memories become easier to find (Hebbian learning)
- **Automatic Decay** - Irrelevant memories fade over time
- **Knowledge Graph** - Related memories surface together

## How It Works

```
First run → Downloads server (~15MB) + embedding model (~23MB)
Server runs locally at http://localhost:3030
No cloud, no API keys needed (auto-generated)
```

## Commands

| Command | Args | Description |
|---------|------|-------------|
| `remember` | `<content>` | Store a memory |
| `recall` | `<query>` | Search memories by meaning |
| `proactive` | `<context>` | Get relevant memories for current context |
| `stats` | | Get memory counts and health |
| `forget` | `<memory_id>` | Delete a specific memory |
| `context` | | Get summary of recent memories |

## Options

| Option | Default | Description |
|--------|---------|-------------|
| `--type` | Context | Memory type: Decision, Learning, Error, Discovery, Pattern, Context, Task, Observation |
| `--tags` | | Comma-separated tags for organization |
| `--limit` | 5 | Number of results to return |

## Memory Types

| Type | When to Use |
|------|-------------|
| Decision | User choices, architectural decisions |
| Learning | New knowledge gained |
| Error | Bugs found and fixes |
| Discovery | Insights, aha moments |
| Pattern | Recurring behaviors |
| Context | Background information |
| Task | Work in progress |
| Observation | General notes |

## Examples

```bash
# Store a decision
python3 scripts/shodh_memory.py remember "User prefers PostgreSQL over MongoDB" --type Decision --tags "database,architecture"

# Store a learning
python3 scripts/shodh_memory.py remember "The API requires OAuth2 with PKCE flow" --type Learning --tags "auth,api"

# Recall memories
python3 scripts/shodh_memory.py recall "user preferences" --limit 5

# Proactive context (call at session start)
python3 shodh_memory.py proactive "building authentication system"

# Check memory stats
python3 scripts/shodh_memory.py stats

# Forget a memory
python3 scripts/shodh_memory.py forget abc123
```

## Auto-Start

The install script creates a macOS LaunchAgent that auto-starts the server on login/restart.

To manually start/stop:
```bash
launchctl load ~/Library/LaunchAgents/com.shodh.memory.plist
launchctl unload ~/Library/LaunchAgents/com.shodh.memory.plist
```

## API

The skill calls REST API at `http://localhost:3030/api/*`:
- `POST /api/remember` - Store memory
- `POST /api/recall` - Semantic search
- `POST /api/relevant` - Proactive context
- `GET /api/memories` - List memories
- `DELETE /api/memory/{id}` - Delete memory

## Notes

- Server runs on port 3030 by default
- First run downloads models (~38MB total), works offline after
- All data stored locally in `~/.shodh/` or default location
- Memory types affect importance and decay rate