106 lines
3.2 KiB
Markdown
106 lines
3.2 KiB
Markdown
---
|
|
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
|