yourmemory 1.0.2__tar.gz

yourmemory-1.0.2/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026 Sachit Misra. All rights reserved.
+
+This software, including all source code, algorithms, data structures, scoring
+formulas, and associated documentation (collectively, the "Software"), is the
+exclusive intellectual property of Sachit Misra.
+
+Permission is granted, free of charge, to any individual to use, copy, and
+modify the Software for personal, educational, or non-commercial research
+purposes, subject to the following conditions:
+
+1. ATTRIBUTION — Any use or distribution of the Software, in whole or in part,
+   must retain this copyright notice and clearly attribute Sachit Misra as the
+   original author.
+
+2. NON-COMMERCIAL USE ONLY — The Software, or any derivative work based on it,
+   may not be used, sold, sublicensed, or incorporated into any product or
+   service for commercial purposes without the prior written consent of
+   Sachit Misra. Commercial purposes include, but are not limited to:
+   - Selling access to the Software or any service powered by it
+   - Incorporating the Software into a commercial product or SaaS offering
+   - Using the Software to generate revenue directly or indirectly
+
+3. NO WARRANTY — The Software is provided "as is", without warranty of any
+   kind, express or implied. Sachit Misra shall not be liable for any claim,
+   damages, or other liability arising from the use of the Software.
+
+For commercial licensing inquiries, contact: mishrasachit1@gmail.com

yourmemory-1.0.2/PKG-INFO

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: yourmemory
+Version: 1.0.2
+Summary: Persistent memory for Claude — Ebbinghaus forgetting curve, semantic deduplication, MCP-native
+Author-email: Sachit Misra <mishrasachit1@gmail.com>
+License: Copyright (c) 2026 Sachit Misra. All rights reserved.
+        
+        This software, including all source code, algorithms, data structures, scoring
+        formulas, and associated documentation (collectively, the "Software"), is the
+        exclusive intellectual property of Sachit Misra.
+        
+        Permission is granted, free of charge, to any individual to use, copy, and
+        modify the Software for personal, educational, or non-commercial research
+        purposes, subject to the following conditions:
+        
+        1. ATTRIBUTION — Any use or distribution of the Software, in whole or in part,
+           must retain this copyright notice and clearly attribute Sachit Misra as the
+           original author.
+        
+        2. NON-COMMERCIAL USE ONLY — The Software, or any derivative work based on it,
+           may not be used, sold, sublicensed, or incorporated into any product or
+           service for commercial purposes without the prior written consent of
+           Sachit Misra. Commercial purposes include, but are not limited to:
+           - Selling access to the Software or any service powered by it
+           - Incorporating the Software into a commercial product or SaaS offering
+           - Using the Software to generate revenue directly or indirectly
+        
+        3. NO WARRANTY — The Software is provided "as is", without warranty of any
+           kind, express or implied. Sachit Misra shall not be liable for any claim,
+           damages, or other liability arising from the use of the Software.
+        
+        For commercial licensing inquiries, contact: mishrasachit1@gmail.com
+        
+Project-URL: Homepage, https://github.com/sachitrafa/cognitive-ai-memory
+Project-URL: Repository, https://github.com/sachitrafa/cognitive-ai-memory
+Keywords: mcp,claude,memory,ebbinghaus,ai,sqlite,postgresql
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi
+Requires-Dist: uvicorn[standard]
+Requires-Dist: psycopg2-binary
+Requires-Dist: pgvector
+Requires-Dist: python-dotenv
+Requires-Dist: httpx
+Requires-Dist: apscheduler
+Requires-Dist: mcp
+Requires-Dist: spacy<4.0,>=3.7
+Requires-Dist: sentence-transformers
+Requires-Dist: numpy
+Requires-Dist: python-dateutil
+Dynamic: license-file
+
+# YourMemory
+
+**+16pp better recall than Mem0 on LoCoMo. 100% stale memory precision. Biologically-inspired memory decay for AI agents.**
+
+Persistent memory for Claude that works like human memory — important things stick, forgotten things fade, outdated facts get demoted automatically.
+
+> Early stage — feedback and ideas welcome.
+
+---
+
+## Benchmarks
+
+Evaluated against Mem0 (free tier) on the public [LoCoMo dataset](https://github.com/snap-research/locomo) (Snap Research) — 10 conversation pairs, 200 QA pairs total.
+
+| Metric | YourMemory | Mem0 | Margin |
+|--------|:----------:|:----:|:------:|
+| LoCoMo Recall@5 *(200 QA pairs)* | **34%** | 18% | **+16pp** |
+| Stale Memory Precision *(5 contradiction pairs)* | **100%** | 0% | **+100pp** |
+| Memories pruned *(noise reduction)* | **20%** | 0% | — |
+
+Full methodology and per-sample results in [BENCHMARKS.md](BENCHMARKS.md).
+Read the writeup: [I built memory decay for AI agents using the Ebbinghaus forgetting curve](https://dev.to/sachit_mishra_686a94d1bb5/i-built-memory-decay-for-ai-agents-using-the-ebbinghaus-forgetting-curve-1b0e)
+
+---
+
+## How it works
+
+### Ebbinghaus Forgetting Curve
+
+```
+base_λ      = DECAY_RATES[category]
+effective_λ = base_λ × (1 - importance × 0.8)
+strength    = importance × e^(-effective_λ × days) × (1 + recall_count × 0.2)
+score       = cosine_similarity × strength
+```
+
+Decay rate varies by **category** — failure memories fade fast, strategies persist longer:
+
+| Category | base λ | survives without recall | use case |
+|----------|--------|------------------------|----------|
+| `strategy` | 0.10 | ~38 days | What worked — successful patterns |
+| `fact` | 0.16 | ~24 days | User preferences, identity |
+| `assumption` | 0.20 | ~19 days | Inferred context |
+| `failure` | 0.35 | ~11 days | What went wrong — environment-specific errors |
+
+Importance additionally modulates the decay rate within each category. Memories recalled frequently gain `recall_count` boosts that counteract decay. Memories below strength `0.05` are pruned automatically.
+
+---
+
+## Setup
+
+**Zero infrastructure required** — uses SQLite out of the box. Two commands and you're done.
+
+### 1. Install
+
+```bash
+git clone https://github.com/sachitrafa/cognitive-ai-memory
+cd cognitive-ai-memory
+pip install .
+```
+
+This installs all dependencies including the spaCy model and sentence-transformers embedding model. No separate download steps needed.
+
+### 2. Wire into Claude
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "yourmemory": {
+      "command": "yourmemory"
+    }
+  }
+}
+```
+
+Reload Claude Code (`Cmd+Shift+P` → `Developer: Reload Window`).
+
+The database is created automatically at `~/.yourmemory/memories.db` on first use. No `.env` file needed.
+
+### 3. Add memory instructions to your project
+
+Copy `sample_CLAUDE.md` into your project root as `CLAUDE.md` and replace:
+- `YOUR_NAME` — your name (e.g. `Alice`)
+- `YOUR_USER_ID` — used to namespace memories (e.g. `alice`)
+
+Claude will now follow the recall → store → update workflow automatically on every task.
+
+---
+
+### PostgreSQL (optional — for teams or large datasets)
+
+If you have PostgreSQL + pgvector, create a `.env` file:
+
+```bash
+DATABASE_URL=postgresql://YOUR_USER@localhost:5432/yourmemory
+```
+
+The backend is selected automatically — `postgresql://` in `DATABASE_URL` → Postgres + pgvector, anything else → SQLite.
+
+**macOS**
+```bash
+brew install postgresql@16 pgvector && brew services start postgresql@16
+createdb yourmemory
+```
+
+**Ubuntu / Debian**
+```bash
+sudo apt install postgresql postgresql-contrib postgresql-16-pgvector
+createdb yourmemory
+```
+
+> **One-liner setup script** (macOS/Linux): `bash scripts/setup_db.sh` handles install + DB creation automatically.
+
+---
+
+## MCP Tools
+
+| Tool | When to call |
+|------|-------------|
+| `recall_memory` | Start of every task — surface relevant context |
+| `store_memory` | After learning a new preference, fact, failure, or strategy |
+| `update_memory` | When a recalled memory is outdated or needs merging |
+
+`store_memory` accepts an optional `category` parameter to control decay rate:
+
+```python
+# Failure — decays in ~11 days (environment changes fast)
+store_memory(
+    content="OAuth for client X fails — redirect URI must be app.example.com",
+    importance=0.6,
+    category="failure"
+)
+
+# Strategy — decays in ~38 days (successful patterns stay relevant)
+store_memory(
+    content="Cursor pagination fixed the 30s timeout on large user queries",
+    importance=0.7,
+    category="strategy"
+)
+```
+
+### Example session
+
+```
+User: "I prefer tabs over spaces in all my Python projects"
+
+Claude:
+  → recall_memory("tabs spaces Python preferences")   # nothing found
+  → store_memory("Sachit prefers tabs over spaces in Python", importance=0.9, category="fact")
+
+Next session:
+  → recall_memory("Python formatting")
+  ← {"content": "Sachit prefers tabs over spaces in Python", "strength": 0.87}
+  → Claude now knows without being told again
+```
+
+---
+
+## Decay Job
+
+Runs automatically every 24 hours on startup — no cron needed. Memories below strength `0.05` are pruned.
+
+---
+
+## REST API
+
+```bash
+# Store
+curl -X POST http://localhost:8000/memories \
+  -H "Content-Type: application/json" \
+  -d '{"userId":"u1","content":"Prefers dark mode","importance":0.8}'
+
+# Retrieve
+curl -X POST http://localhost:8000/retrieve \
+  -H "Content-Type: application/json" \
+  -d '{"userId":"u1","query":"UI preferences"}'
+
+# List all
+curl "http://localhost:8000/memories?userId=u1"
+
+# Update
+curl -X PUT http://localhost:8000/memories/42 \
+  -H "Content-Type: application/json" \
+  -d '{"content":"Prefers dark mode in all apps","importance":0.85}'
+
+# Delete
+curl -X DELETE http://localhost:8000/memories/42
+```
+
+---
+
+## Stack
+
+- **PostgreSQL + pgvector** — vector similarity search
+- **sentence-transformers** — local embeddings (`all-mpnet-base-v2`, 768 dims, no external service needed)
+- **FastAPI** — REST server
+- **APScheduler** — automatic 24h decay job
+- **MCP** — Claude integration via Model Context Protocol
+
+---
+
+## Architecture
+
+```
+Claude Code
+    │
+    ├── recall_memory(query)
+    │       └── embed → cosine similarity → score = sim × strength → top-k
+    │
+    ├── store_memory(content, importance, category?)
+    │       └── is_question? → reject
+    │           category: fact | assumption | failure | strategy
+    │           embed() → INSERT memories
+    │
+    └── update_memory(id, new_content)
+            └── embed(new_content) → UPDATE memories
+
+PostgreSQL (pgvector)
+    └── memories
+        ├── embedding vector(768)
+        ├── importance float
+        ├── recall_count int
+        └── last_accessed_at
+```
+
+---
+
+## Dataset Reference
+
+Benchmarks use the [LoCoMo](https://github.com/snap-research/locomo) dataset by Snap Research — a public long-context memory benchmark for multi-session dialogue.
+
+> Maharana et al. (2024). *LoCoMo: Long Context Multimodal Benchmark for Dialogue.* Snap Research.
+
+---
+
+## License
+
+Copyright (c) 2026 **Sachit Misra**. All rights reserved.
+
+All source code, algorithms, scoring formulas, data structures, and associated documentation in this repository are the exclusive intellectual property of Sachit Misra.
+
+**Non-commercial use only.** Personal, educational, and research use is permitted with attribution. Commercial use — including incorporation into products, SaaS offerings, or revenue-generating services — requires prior written consent.
+
+For commercial licensing: mishrasachit1@gmail.com
+
+See [LICENSE](LICENSE) for full terms.

yourmemory-1.0.2/README.md

@@ -0,0 +1,248 @@
+# YourMemory
+
+**+16pp better recall than Mem0 on LoCoMo. 100% stale memory precision. Biologically-inspired memory decay for AI agents.**
+
+Persistent memory for Claude that works like human memory — important things stick, forgotten things fade, outdated facts get demoted automatically.
+
+> Early stage — feedback and ideas welcome.
+
+---
+
+## Benchmarks
+
+Evaluated against Mem0 (free tier) on the public [LoCoMo dataset](https://github.com/snap-research/locomo) (Snap Research) — 10 conversation pairs, 200 QA pairs total.
+
+| Metric | YourMemory | Mem0 | Margin |
+|--------|:----------:|:----:|:------:|
+| LoCoMo Recall@5 *(200 QA pairs)* | **34%** | 18% | **+16pp** |
+| Stale Memory Precision *(5 contradiction pairs)* | **100%** | 0% | **+100pp** |
+| Memories pruned *(noise reduction)* | **20%** | 0% | — |
+
+Full methodology and per-sample results in [BENCHMARKS.md](BENCHMARKS.md).
+Read the writeup: [I built memory decay for AI agents using the Ebbinghaus forgetting curve](https://dev.to/sachit_mishra_686a94d1bb5/i-built-memory-decay-for-ai-agents-using-the-ebbinghaus-forgetting-curve-1b0e)
+
+---
+
+## How it works
+
+### Ebbinghaus Forgetting Curve
+
+```
+base_λ      = DECAY_RATES[category]
+effective_λ = base_λ × (1 - importance × 0.8)
+strength    = importance × e^(-effective_λ × days) × (1 + recall_count × 0.2)
+score       = cosine_similarity × strength
+```
+
+Decay rate varies by **category** — failure memories fade fast, strategies persist longer:
+
+| Category | base λ | survives without recall | use case |
+|----------|--------|------------------------|----------|
+| `strategy` | 0.10 | ~38 days | What worked — successful patterns |
+| `fact` | 0.16 | ~24 days | User preferences, identity |
+| `assumption` | 0.20 | ~19 days | Inferred context |
+| `failure` | 0.35 | ~11 days | What went wrong — environment-specific errors |
+
+Importance additionally modulates the decay rate within each category. Memories recalled frequently gain `recall_count` boosts that counteract decay. Memories below strength `0.05` are pruned automatically.
+
+---
+
+## Setup
+
+**Zero infrastructure required** — uses SQLite out of the box. Two commands and you're done.
+
+### 1. Install
+
+```bash
+git clone https://github.com/sachitrafa/cognitive-ai-memory
+cd cognitive-ai-memory
+pip install .
+```
+
+This installs all dependencies including the spaCy model and sentence-transformers embedding model. No separate download steps needed.
+
+### 2. Wire into Claude
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "yourmemory": {
+      "command": "yourmemory"
+    }
+  }
+}
+```
+
+Reload Claude Code (`Cmd+Shift+P` → `Developer: Reload Window`).
+
+The database is created automatically at `~/.yourmemory/memories.db` on first use. No `.env` file needed.
+
+### 3. Add memory instructions to your project
+
+Copy `sample_CLAUDE.md` into your project root as `CLAUDE.md` and replace:
+- `YOUR_NAME` — your name (e.g. `Alice`)
+- `YOUR_USER_ID` — used to namespace memories (e.g. `alice`)
+
+Claude will now follow the recall → store → update workflow automatically on every task.
+
+---
+
+### PostgreSQL (optional — for teams or large datasets)
+
+If you have PostgreSQL + pgvector, create a `.env` file:
+
+```bash
+DATABASE_URL=postgresql://YOUR_USER@localhost:5432/yourmemory
+```
+
+The backend is selected automatically — `postgresql://` in `DATABASE_URL` → Postgres + pgvector, anything else → SQLite.
+
+**macOS**
+```bash
+brew install postgresql@16 pgvector && brew services start postgresql@16
+createdb yourmemory
+```
+
+**Ubuntu / Debian**
+```bash
+sudo apt install postgresql postgresql-contrib postgresql-16-pgvector
+createdb yourmemory
+```
+
+> **One-liner setup script** (macOS/Linux): `bash scripts/setup_db.sh` handles install + DB creation automatically.
+
+---
+
+## MCP Tools
+
+| Tool | When to call |
+|------|-------------|
+| `recall_memory` | Start of every task — surface relevant context |
+| `store_memory` | After learning a new preference, fact, failure, or strategy |
+| `update_memory` | When a recalled memory is outdated or needs merging |
+
+`store_memory` accepts an optional `category` parameter to control decay rate:
+
+```python
+# Failure — decays in ~11 days (environment changes fast)
+store_memory(
+    content="OAuth for client X fails — redirect URI must be app.example.com",
+    importance=0.6,
+    category="failure"
+)
+
+# Strategy — decays in ~38 days (successful patterns stay relevant)
+store_memory(
+    content="Cursor pagination fixed the 30s timeout on large user queries",
+    importance=0.7,
+    category="strategy"
+)
+```
+
+### Example session
+
+```
+User: "I prefer tabs over spaces in all my Python projects"
+
+Claude:
+  → recall_memory("tabs spaces Python preferences")   # nothing found
+  → store_memory("Sachit prefers tabs over spaces in Python", importance=0.9, category="fact")
+
+Next session:
+  → recall_memory("Python formatting")
+  ← {"content": "Sachit prefers tabs over spaces in Python", "strength": 0.87}
+  → Claude now knows without being told again
+```
+
+---
+
+## Decay Job
+
+Runs automatically every 24 hours on startup — no cron needed. Memories below strength `0.05` are pruned.
+
+---
+
+## REST API
+
+```bash
+# Store
+curl -X POST http://localhost:8000/memories \
+  -H "Content-Type: application/json" \
+  -d '{"userId":"u1","content":"Prefers dark mode","importance":0.8}'
+
+# Retrieve
+curl -X POST http://localhost:8000/retrieve \
+  -H "Content-Type: application/json" \
+  -d '{"userId":"u1","query":"UI preferences"}'
+
+# List all
+curl "http://localhost:8000/memories?userId=u1"
+
+# Update
+curl -X PUT http://localhost:8000/memories/42 \
+  -H "Content-Type: application/json" \
+  -d '{"content":"Prefers dark mode in all apps","importance":0.85}'
+
+# Delete
+curl -X DELETE http://localhost:8000/memories/42
+```
+
+---
+
+## Stack
+
+- **PostgreSQL + pgvector** — vector similarity search
+- **sentence-transformers** — local embeddings (`all-mpnet-base-v2`, 768 dims, no external service needed)
+- **FastAPI** — REST server
+- **APScheduler** — automatic 24h decay job
+- **MCP** — Claude integration via Model Context Protocol
+
+---
+
+## Architecture
+
+```
+Claude Code
+    │
+    ├── recall_memory(query)
+    │       └── embed → cosine similarity → score = sim × strength → top-k
+    │
+    ├── store_memory(content, importance, category?)
+    │       └── is_question? → reject
+    │           category: fact | assumption | failure | strategy
+    │           embed() → INSERT memories
+    │
+    └── update_memory(id, new_content)
+            └── embed(new_content) → UPDATE memories
+
+PostgreSQL (pgvector)
+    └── memories
+        ├── embedding vector(768)
+        ├── importance float
+        ├── recall_count int
+        └── last_accessed_at
+```
+
+---
+
+## Dataset Reference
+
+Benchmarks use the [LoCoMo](https://github.com/snap-research/locomo) dataset by Snap Research — a public long-context memory benchmark for multi-session dialogue.
+
+> Maharana et al. (2024). *LoCoMo: Long Context Multimodal Benchmark for Dialogue.* Snap Research.
+
+---
+
+## License
+
+Copyright (c) 2026 **Sachit Misra**. All rights reserved.
+
+All source code, algorithms, scoring formulas, data structures, and associated documentation in this repository are the exclusive intellectual property of Sachit Misra.
+
+**Non-commercial use only.** Personal, educational, and research use is permitted with attribution. Commercial use — including incorporation into products, SaaS offerings, or revenue-generating services — requires prior written consent.
+
+For commercial licensing: mishrasachit1@gmail.com
+
+See [LICENSE](LICENSE) for full terms.