retainr 0.2.0__tar.gz

retainr-0.2.0/.env.example

@@ -0,0 +1 @@
+HF_TOKEN=your_token_here

retainr-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v
+
+      - name: Lint
+        run: uv run ruff check memoryos/

retainr-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env
+.memory.db

retainr-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

retainr-0.2.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: retainr
+Version: 0.2.0
+Summary: Persistent, queryable AI memory for any Python app — local-first, zero API cost
+Project-URL: Homepage, https://github.com/Devarajan8/memoryos
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: faiss-cpu>=1.8.0
+Requires-Dist: groq>=1.2.0
+Requires-Dist: sentence-transformers>=2.7.0
+Description-Content-Type: text/markdown
+
+# memoryos
+
+[![CI](https://github.com/Devarajan8/memoryos/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Devarajan8/memoryos/actions)
+
+> Persistent, queryable memory for any Python AI app — local-first, zero API cost.
+
+[![PyPI version](https://badge.fury.io/py/memoryos-official.svg)](https://pypi.org/project/memoryos-official/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## What is it?
+
+`memoryos` gives any AI app a long-term memory layer — without needing an API key, a cloud service, or a database server.
+
+Store things. Recall them semantically. Forget them. All locally.
+
+```python
+from memoryos import Memory
+
+mem = Memory(user_id="arjun")
+
+mem.remember("I prefer dark mode and use VS Code")
+mem.remember("Currently building a job application assistant")
+mem.remember("I like concise answers over long explanations")
+
+results = mem.recall("what tools does the user prefer?")
+for r in results:
+    print(f"[{r['score']:.3f}] {r['text']}")
+```
+
+```
+[0.412] I prefer dark mode and use VS Code
+[0.289] I like concise answers over long explanations
+```
+
+## CLI Demo
+
+![alt text](image.png)
+
+### Stats
+
+![alt text](image-1.png)
+
+---
+
+## Install
+
+```bash
+pip install memoryos-official
+```
+
+---
+
+## Features
+
+- **Semantic recall** — finds memories by meaning, not exact keywords
+- **Memory decay** — old memories fade in relevance automatically
+- **Importance scoring** — weight memories by how significant they are
+- **Tags** — organize memories into namespaces
+- **Forget & clear** — GDPR-friendly deletion
+- **Local-first** — uses FAISS + SQLite, no external services
+- **Zero cost** — no API keys, no cloud, runs on your machine
+
+---
+
+## API Reference
+
+### `Memory(user_id, db_path)`
+
+```python
+mem = Memory(user_id="alice", db_path="memory.db")
+```
+
+| Param     | Default       | Description                                           |
+| --------- | ------------- | ----------------------------------------------------- |
+| `user_id` | `"default"`   | Isolates memories per user                            |
+| `db_path` | `"memory.db"` | SQLite file path. Use `":memory:"` for in-RAM (tests) |
+
+---
+
+### `remember(text, tags, importance, decay_days)`
+
+Store a memory.
+
+```python
+mid = mem.remember(
+    "User just got promoted to SDE-2",
+    tags=["career", "milestone"],
+    importance=0.9,   # 0.0–1.0, default 0.5
+    decay_days=90,    # score halves every 90 days, 0 = no decay
+)
+```
+
+Returns: `str` — the memory ID (use it to `forget()` later)
+
+---
+
+### `recall(query, top_k)`
+
+Find the most semantically relevant memories.
+
+```python
+results = mem.recall("what is the user's job status?", top_k=3)
+# [{"id": ..., "text": ..., "score": 0.87, "tags": [...], ...}]
+```
+
+---
+
+### `forget(memory_id)`
+
+Delete a specific memory.
+
+```python
+mem.forget(mid)
+```
+
+---
+
+### `clear()`
+
+Wipe all memories for this user.
+
+```python
+mem.clear()
+```
+
+---
+
+### `export(filepath)`
+
+Backup all memories to JSON.
+
+```python
+mem.export("my_memories.json")
+```
+
+---
+
+## How it works
+
+1. **`remember()`** → text is embedded using `sentence-transformers` (all-MiniLM-L6-v2, runs locally) → vector stored in FAISS, metadata in SQLite
+2. **`recall()`** → query is embedded → FAISS finds top-k nearest vectors → SQLite returns the original text
+3. **Scoring** → final score = cosine similarity × (0.7 + 0.3 × decayed importance)
+
+---
+
+## Why not mem0 / Zep / etc.?
+
+|                | memoryos | mem0       | Zep        |
+| -------------- | -------- | ---------- | ---------- |
+| Local-first    | ✅       | ❌         | ❌         |
+| API key needed | ❌       | ✅         | ✅         |
+| Cost           | Free     | Paid tiers | Paid tiers |
+| Memory decay   | ✅       | ❌         | ❌         |
+| `pip install`  | ✅       | ✅         | ✅         |
+
+---
+
+## Stack
+
+- [`sentence-transformers`](https://www.sbert.net/) — local text embeddings
+- [`faiss-cpu`](https://github.com/facebookresearch/faiss) — vector similarity search
+- `sqlite3` — metadata storage (built into Python)
+
+---
+
+## License
+
+MIT © Devarajan

retainr-0.2.0/README.md

@@ -0,0 +1,171 @@
+# memoryos
+
+[![CI](https://github.com/Devarajan8/memoryos/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Devarajan8/memoryos/actions)
+
+> Persistent, queryable memory for any Python AI app — local-first, zero API cost.
+
+[![PyPI version](https://badge.fury.io/py/memoryos-official.svg)](https://pypi.org/project/memoryos-official/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## What is it?
+
+`memoryos` gives any AI app a long-term memory layer — without needing an API key, a cloud service, or a database server.
+
+Store things. Recall them semantically. Forget them. All locally.
+
+```python
+from memoryos import Memory
+
+mem = Memory(user_id="arjun")
+
+mem.remember("I prefer dark mode and use VS Code")
+mem.remember("Currently building a job application assistant")
+mem.remember("I like concise answers over long explanations")
+
+results = mem.recall("what tools does the user prefer?")
+for r in results:
+    print(f"[{r['score']:.3f}] {r['text']}")
+```
+
+```
+[0.412] I prefer dark mode and use VS Code
+[0.289] I like concise answers over long explanations
+```
+
+## CLI Demo
+
+![alt text](image.png)
+
+### Stats
+
+![alt text](image-1.png)
+
+---
+
+## Install
+
+```bash
+pip install memoryos-official
+```
+
+---
+
+## Features
+
+- **Semantic recall** — finds memories by meaning, not exact keywords
+- **Memory decay** — old memories fade in relevance automatically
+- **Importance scoring** — weight memories by how significant they are
+- **Tags** — organize memories into namespaces
+- **Forget & clear** — GDPR-friendly deletion
+- **Local-first** — uses FAISS + SQLite, no external services
+- **Zero cost** — no API keys, no cloud, runs on your machine
+
+---
+
+## API Reference
+
+### `Memory(user_id, db_path)`
+
+```python
+mem = Memory(user_id="alice", db_path="memory.db")
+```
+
+| Param     | Default       | Description                                           |
+| --------- | ------------- | ----------------------------------------------------- |
+| `user_id` | `"default"`   | Isolates memories per user                            |
+| `db_path` | `"memory.db"` | SQLite file path. Use `":memory:"` for in-RAM (tests) |
+
+---
+
+### `remember(text, tags, importance, decay_days)`
+
+Store a memory.
+
+```python
+mid = mem.remember(
+    "User just got promoted to SDE-2",
+    tags=["career", "milestone"],
+    importance=0.9,   # 0.0–1.0, default 0.5
+    decay_days=90,    # score halves every 90 days, 0 = no decay
+)
+```
+
+Returns: `str` — the memory ID (use it to `forget()` later)
+
+---
+
+### `recall(query, top_k)`
+
+Find the most semantically relevant memories.
+
+```python
+results = mem.recall("what is the user's job status?", top_k=3)
+# [{"id": ..., "text": ..., "score": 0.87, "tags": [...], ...}]
+```
+
+---
+
+### `forget(memory_id)`
+
+Delete a specific memory.
+
+```python
+mem.forget(mid)
+```
+
+---
+
+### `clear()`
+
+Wipe all memories for this user.
+
+```python
+mem.clear()
+```
+
+---
+
+### `export(filepath)`
+
+Backup all memories to JSON.
+
+```python
+mem.export("my_memories.json")
+```
+
+---
+
+## How it works
+
+1. **`remember()`** → text is embedded using `sentence-transformers` (all-MiniLM-L6-v2, runs locally) → vector stored in FAISS, metadata in SQLite
+2. **`recall()`** → query is embedded → FAISS finds top-k nearest vectors → SQLite returns the original text
+3. **Scoring** → final score = cosine similarity × (0.7 + 0.3 × decayed importance)
+
+---
+
+## Why not mem0 / Zep / etc.?
+
+|                | memoryos | mem0       | Zep        |
+| -------------- | -------- | ---------- | ---------- |
+| Local-first    | ✅       | ❌         | ❌         |
+| API key needed | ❌       | ✅         | ✅         |
+| Cost           | Free     | Paid tiers | Paid tiers |
+| Memory decay   | ✅       | ❌         | ❌         |
+| `pip install`  | ✅       | ✅         | ✅         |
+
+---
+
+## Stack
+
+- [`sentence-transformers`](https://www.sbert.net/) — local text embeddings
+- [`faiss-cpu`](https://github.com/facebookresearch/faiss) — vector similarity search
+- `sqlite3` — metadata storage (built into Python)
+
+---
+
+## License
+
+MIT © Devarajan

retainr-0.2.0/examples/basic_usage.py

@@ -0,0 +1,28 @@
+from memoryos import Memory
+
+mem = Memory(user_id="arjun")
+mem.remember("I prefer dark mode and use VS Code")
+mem.remember("Currently building memoryos, a local memory library")
+mem.remember("I like concise answers over long explanations")
+
+results = mem.recall("what is the user building?")
+for r in results:
+    print(f"[{r['score']:.3f}] {r['text']}")
+    
+
+from memoryos import Memory
+
+mem = Memory(user_id="arjun", db_path=":memory:")
+mid = mem.remember("Old info", decay_days=1)
+mem.remember("User prefers Python", importance=0.9)
+mem.remember("User said hi", importance=0.1)
+mem.remember("Wants dark UI", tags=["ui", "preference"])
+
+results = mem.recall("what does the user prefer?", top_k=3)
+for r in results:
+    print(f"[{r['score']:.3f}] {r['text']}")
+
+mem.forget(mid)
+print("After forget:", len(mem.recall("old info")), "results")
+mem.clear()
+print("After clear:", len(mem.recall("anything")), "results")

retainr-0.2.0/examples/chatbot_with_memory.py

@@ -0,0 +1,109 @@
+
+import os
+from memoryos import Memory
+
+from pathlib import Path
+
+_env_file = Path(__file__).parent.parent / ".env"
+if _env_file.exists():
+    for line in _env_file.read_text().splitlines():
+        line = line.strip()
+        if line and not line.startswith("#") and "=" in line:
+            key, _, value = line.partition("=")
+            os.environ.setdefault(key.strip(), value.strip().strip('"').strip("'"))
+
+
+try:
+    from groq import Groq
+    HAS_GROQ = True
+except ImportError:
+    HAS_GROQ = False
+
+def get_memory_context(mem: Memory, user_message: str) -> str:
+
+    results = mem.recall(user_message, top_k=1)
+    if not results:
+        return ""
+    context = "\n".join(f"- {r['text']}" for r in results)
+    return f"\nRelevant things I remember about you:\n{context}\n"
+
+
+def chat_with_memory():
+    mem = Memory(user_id="demo_user", db_path="chatbot_memory.db")
+    print("Chatbot with memory (type 'quit' to exit, 'forget all' to clear)")
+    print("\n")
+
+    if HAS_GROQ:
+        client = Groq(api_key=os.environ.get("GROQ_API_KEY"))
+    else:
+        print("  Groq not installed — running in echo mode (no LLM)")
+        print("   Install: pip install groq")
+        print("   Get free API key: console.groq.com")
+        print()
+
+    conversation_history = []
+
+    while True:
+        user_input = input("You: ").strip()
+        if not user_input:
+            continue
+        if user_input.lower() == "quit":
+            break
+        if user_input.lower() == "forget all":
+            mem.clear()
+            print("Bot: Memory cleared.\n")
+            continue
+        
+        def should_remember(user_input: str, client) -> bool:
+
+            response = client.chat.completions.create(
+                model="llama-3.3-70b-versatile",
+                messages=[{
+                    "role": "user",
+                    "content": (
+                        f"Does this message contain a personal fact, preference, or "
+                        f"long-term information worth remembering about the user?\n\n"
+                        f"Message: \"{user_input}\"\n\n"
+                        f"Reply with only YES or NO."
+                    )
+                }],
+                max_tokens=5,
+                temperature=0,   
+            )
+            answer = response.choices[0].message.content.strip().upper()
+            return answer.startswith("YES")
+        
+        
+        if HAS_GROQ and should_remember(user_input, client):
+            mem.remember(user_input, importance=0.8)
+            print(" Stored in memory")
+
+    
+        memory_context = get_memory_context(mem, user_input)
+
+        if HAS_GROQ:
+            system_prompt = (
+                "You are a helpful assistant with memory. "
+                "Use the remembered context to personalise your responses."
+                + memory_context
+            )
+            conversation_history.append({"role": "user", "content": user_input})
+            response = client.chat.completions.create(
+                model="llama-3.3-70b-versatile",
+                messages=[{"role": "system", "content": system_prompt}]
+                         + conversation_history[-6:],  
+            )
+            reply = response.choices[0].message.content
+            conversation_history.append({"role": "assistant", "content": reply})
+            print(f"Bot: {reply}\n")
+        else:
+            # Demo mode without LLM
+            if memory_context:
+                print(f"Bot: [Echo + Memory] {user_input}")
+                print(f"     Context I have:{memory_context}")
+            else:
+                print(f"Bot: [Echo] {user_input}\n")
+
+
+if __name__ == "__main__":
+    chat_with_memory()

retainr-0.2.0/hello.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from memoryos!")
+
+
+if __name__ == "__main__":
+    main()

retainr-0.2.0/memoryos/__init__.py

@@ -0,0 +1,4 @@
+from .memory import Memory
+
+__all__ = ["Memory"]
+__version__ = "0.1.0"

retainr-0.2.0/memoryos/__main__.py

@@ -0,0 +1,65 @@
+
+import sys
+from memoryos import Memory, __version__
+
+import os
+from pathlib import Path
+
+
+_env_file = Path(__file__).parent.parent / ".env"
+if _env_file.exists():
+    for line in _env_file.read_text().splitlines():
+        line = line.strip()
+        if line and not line.startswith("#") and "=" in line:
+            key, _, value = line.partition("=")
+            os.environ.setdefault(key.strip(), value.strip().strip('"').strip("'"))
+
+
+def main():
+    print(f"memoryos v{__version__} — local AI memory")
+    print("Commands: remember <text> | recall <query> | clear | stats")
+    print()
+
+    mem = Memory(user_id="cli_user", db_path="cli_memory.db")
+
+    if len(sys.argv) < 2:
+        print("Usage: python -m memoryos remember 'some text'")
+        print("       python -m memoryos recall 'your query'")
+        print("       python -m memoryos clear")
+        print("       python -m memoryos stats")
+        return
+
+    command = sys.argv[1].lower()
+    args = " ".join(sys.argv[2:])
+
+    if command == "remember":
+        if not args:
+            print("Error: provide text to remember")
+            return
+        mid = mem.remember(args)
+        print(f"Remembered (id: {mid[:8]}...)")
+
+    elif command == "recall":
+        if not args:
+            print("Error: provide a query")
+            return
+        results = mem.recall(args, top_k=1)
+        if not results:
+            print("No memories found.")
+        for r in results:
+            print(f"[{r['score']:.3f}] {r['text']}")
+
+    elif command == "clear":
+        mem.clear()
+        print("  All memories cleared.")
+
+    elif command == "stats":
+        results = mem.recall("", top_k=99999)
+        print(f"Total memories: {len(results)}")
+
+    else:
+        print(f"Unknown command: {command}")
+
+
+if __name__ == "__main__":
+    main()

retainr-0.2.0/memoryos/embedder.py

@@ -0,0 +1,11 @@
+from sentence_transformers import SentenceTransformer
+import numpy as np
+
+class Embedder:
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2"):
+
+        self.model = SentenceTransformer(model_name)
+
+    def encode(self, text: str) -> np.ndarray:
+
+        return self.model.encode(text, normalize_embeddings=True)

retainr-0.2.0/memoryos/memory.py

@@ -0,0 +1,38 @@
+import time
+from .embedder import Embedder
+from .store import VectorStore
+
+class Memory:
+    def __init__(self, user_id: str = "default", db_path: str = "memory.db"):
+        self.user_id = user_id
+        self.embedder = Embedder()
+        self.store = VectorStore(db_path)
+        
+    def forget(self, memory_id: str) -> bool:
+        return self.store.delete(memory_id)
+
+    def clear(self):
+        self.store.clear(self.user_id)
+
+    def export(self, filepath: str):
+        import json
+        # Get all memories (high top_k to get everything)
+        results = self.store.search(self.user_id,
+                                    self.embedder.encode(""), top_k=99999)
+        with open(filepath, "w") as f:
+            json.dump(results, f, indent=2)
+
+    def remember(self, text: str, tags: list[str] = [],
+                 importance: float = 0.5, decay_days: int = 0) -> str:
+
+        embedding = self.embedder.encode(text)
+        return self.store.save(
+            user_id=self.user_id, text=text, embedding=embedding,
+            tags=tags, timestamp=time.time(),
+            importance=importance, decay_days=decay_days,
+        )
+
+    def recall(self, query: str, top_k: int = 1) -> list[dict]:
+
+        query_embedding = self.embedder.encode(query)
+        return self.store.search(self.user_id, query_embedding, top_k)