local-persona-memory 0.2.0__tar.gz

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

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/
+
+      - name: Type check with mypy
+        run: mypy src/ --ignore-missing-imports
+        continue-on-error: true   # Don't fail CI on mypy warnings during early dev
+
+      - name: Run tests
+        run: pytest tests/ -v --cov=src/local_persona_memory --cov-report=term-missing
+
+      - name: Build package (verify it builds cleanly)
+        run: python -m build
+
+  publish:
+    # Only publish to PyPI when you push a version tag like v0.1.0
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install build twine
+      - run: python -m build
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

local_persona_memory-0.2.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checking
+.mypy_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Local memory data — never commit user memories!
+~/.local_persona_memory/
+*.chroma/
+
+# Environment
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db

local_persona_memory-0.2.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## [0.2.0] - 2024-XX-XX
+
+### Fixed (Breaking warnings resolved)
+- Removed `langchain-community` dependency (was being sunset)
+- PDF loading now uses `pypdf` directly — no deprecated wrapper
+- `Document` type now from `langchain-core` (stable)
+- `RecursiveCharacterTextSplitter` now from `langchain-text-splitters` (standalone)
+- No more deprecation warnings on install or import
+
+### Added
+- `add_conversation()` — manually add conversation turns to history
+- `get_conversation_history(last_n)` — retrieve recent chat turns
+- `clear_conversation_history()` — reset in-session history
+- `export_memories(path)` — back up all memories to JSON
+- `import_memories(path, merge)` — restore from JSON backup
+- `memory_summary()` — LLM-generated natural language profile
+- `on_remember` callback hook — fires after every `remember()` call
+- `on_recall` callback hook — fires after every `recall()` call
+- `on_ingest_complete` callback on `DocumentIngester`
+- `remember_conversation` flag on `chat()` to opt out of history tracking
+- Real Ollama integration test suite (`test_real_ollama.py`)
+
+### Changed
+- `pyproject.toml` dependencies updated — `langchain-community` removed
+- Version bumped to `0.2.0`
+
+## [0.1.0] - 2024-XX-XX
+### Added
+- Initial release
+- `PersonaMemoryManager` with `remember()`, `recall()`, `chat()`, `ingest_pdf()`, `forget()`
+- ChromaDB persistent vector storage
+- Any Ollama model support
+- PDF, TXT, MD ingestion
+- User isolation
+- 97 tests, 83% coverage

local_persona_memory-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to local-persona-memory
+
+Thank you for your interest! Here's how to get started.
+
+## Setup
+
+```bash
+git clone https://github.com/yourname/local-persona-memory
+cd local-persona-memory
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install
+```
+
+## Running tests
+
+```bash
+pytest tests/ -v --cov=src/local_persona_memory
+```
+
+## Code style
+
+We use `ruff` for linting:
+```bash
+ruff check src/
+ruff format src/
+```
+
+## Adding a new feature
+
+1. Open an issue first to discuss
+2. Create a branch: `git checkout -b feat/your-feature`
+3. Write tests BEFORE writing code (TDD)
+4. Make tests pass
+5. Open a pull request
+
+## Adding support for a new document type
+
+1. Add the file extension and loader to `SUPPORTED_EXTENSIONS` in `ingestion.py`
+2. Add a test in `tests/test_ingestion.py`
+3. Update the README supported formats table
+
+## Reporting bugs
+
+Include:
+- Python version (`python --version`)
+- Ollama version (`ollama --version`)
+- Model being used
+- Full traceback
+- Minimal reproducible example

local_persona_memory-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

local_persona_memory-0.2.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: local-persona-memory
+Version: 0.2.0
+Summary: Long-term personalized memory for ANY local LLM via Ollama + ChromaDB + LangChain
+Project-URL: Homepage, https://github.com/AbhiLohar/local-persona-memory
+Project-URL: Repository, https://github.com/AbhiLohar/local-persona-memory
+Project-URL: Issues, https://github.com/AbhiLohar/local-persona-memory/issues
+License: MIT License
+        
+        Copyright (c) 2024 Your Name
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai,chromadb,langchain,llm,local-ai,memory,ollama,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: chromadb>=0.5.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langchain-ollama>=0.1.0
+Requires-Dist: langchain-text-splitters>=0.3.0
+Requires-Dist: ollama>=0.2.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pypdf>=4.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tenacity>=8.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# local-persona-memory
+
+> Long-term personalized memory for ANY local LLM running via Ollama.
+
+Your AI assistant forgets everything when the session ends. This library fixes that — permanently, privately, and with zero cloud dependency.
+
+## What it solves
+
+Most RAG libraries are built for searching documents. This library is built for **remembering people**. It stores user preferences, facts, skills, and goals, then injects the most relevant memories into every LLM response automatically.
+
+## Supported models
+
+Works with **any model in the Ollama library**:
+
+| Use case | Recommended model |
+|---|---|
+| General assistant | `llama3`, `llama3.1`, `mistral` |
+| Fast / lightweight | `phi3`, `gemma2:2b`, `tinyllama` |
+| Coding assistant | `codellama`, `deepseek-coder` |
+| Multilingual | `qwen2`, `qwen2.5` |
+| Reasoning | `deepseek-r1`, `qwen2.5:14b` |
+
+## Install
+
+```bash
+pip install local-persona-memory
+```
+
+**Prerequisites:**
+1. [Install Ollama](https://ollama.com)
+2. Pull a model and the embedding model:
+   ```bash
+   ollama pull llama3
+   ollama pull nomic-embed-text
+   ```
+3. Run `ollama serve` (or open the Ollama app)
+
+## Quick start
+
+```python
+from local_persona_memory import PersonaMemoryManager
+
+# Works with any Ollama model
+mem = PersonaMemoryManager(user_id="alice", model="llama3")
+
+# Store memories
+mem.remember("Alice is a Python developer building AI tools")
+mem.remember("Alice prefers concise answers and code examples")
+
+# Learn from documents
+mem.ingest_pdf("notes.pdf")
+
+# Chat with automatic memory context
+response = mem.chat("What should I work on today?")
+print(response)
+
+# Inspect stored memories
+print(f"Stored {mem.memory_count()} memories")
+```
+
+## Advanced usage
+
+```python
+from local_persona_memory import PersonaMemoryManager, LLMConfig, MemoryConfig, MemoryCategory
+
+mem = PersonaMemoryManager(
+    user_id="bob",
+    llm_config=LLMConfig(
+        model="mistral",         # any Ollama model
+        temperature=0.4,
+        context_window=8192,     # increase for larger models
+    ),
+    memory_config=MemoryConfig(
+        top_k_memories=8,        # retrieve more memories per query
+        chunk_size=512,          # PDF chunk size in characters
+        similarity_threshold=0.3,
+        embedding_model="nomic-embed-text",
+    ),
+)
+
+# Categorise memories for better filtering
+mem.remember("Bob knows Rust and Go", category=MemoryCategory.SKILL)
+mem.remember("Bob wants to build a CLI tool", category=MemoryCategory.GOAL)
+
+# Recall with category filter
+skill_memories = mem.recall("programming languages", category=MemoryCategory.SKILL)
+```
+
+## How it works
+
+```
+User message
+     │
+     ▼
+[Embed with nomic-embed-text]
+     │
+     ▼
+[ChromaDB similarity search] ──► Top-K relevant memories
+     │
+     ▼
+[Build prompt: system + memories + message]
+     │
+     ▼
+[Generate with Ollama model]
+     │
+     ▼
+Personalised response
+```
+
+Memories persist to `~/.local_persona_memory/` between sessions. Each user gets an isolated ChromaDB collection.
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md). Open an issue first for large changes.
+
+## License
+
+MIT

local_persona_memory-0.2.0/PUBLISH_GUIDE.md

@@ -0,0 +1,72 @@
+# Step-by-Step: Publishing to PyPI
+
+## Phase 5 — CI/CD (already set up in .github/workflows/ci.yml)
+
+Push to GitHub and CI runs automatically on every push.
+
+## Phase 6 — Publishing to PyPI
+
+### Step 1: Create accounts
+- PyPI (production): https://pypi.org/account/register/
+- TestPyPI (for testing): https://test.pypi.org/account/register/
+
+### Step 2: Create API tokens
+- Go to PyPI → Account Settings → API Tokens
+- Create token scoped to this project
+- Save it somewhere safe — shown only once
+
+### Step 3: Install build tools
+```bash
+pip install build twine
+```
+
+### Step 4: Build the package
+```bash
+cd local-persona-memory
+python -m build
+# Creates: dist/local_persona_memory-0.1.0.tar.gz
+#          dist/local_persona_memory-0.1.0-py3-none-any.whl
+```
+
+### Step 5: Test on TestPyPI first (always do this)
+```bash
+twine upload --repository testpypi dist/*
+# Enter: __token__
+# Enter: your-testpypi-token
+
+# Test install from TestPyPI
+pip install --index-url https://test.pypi.org/simple/ local-persona-memory
+```
+
+### Step 6: Publish to real PyPI
+```bash
+twine upload dist/*
+# Enter: __token__
+# Enter: your-pypi-token
+```
+
+### Step 7: Verify it works
+```bash
+pip install local-persona-memory
+python -c "from local_persona_memory import PersonaMemoryManager; print('Success!')"
+```
+
+## Releasing updates (v0.2.0)
+
+```bash
+# 1. Update version in pyproject.toml: version = "0.2.0"
+# 2. Update CHANGELOG.md
+# 3. Commit: git commit -m "chore: bump version to 0.2.0"
+# 4. Tag: git tag v0.2.0
+# 5. Push tag: git push origin v0.2.0
+# CI/CD automatically builds and publishes!
+```
+
+## Automating publish via GitHub Actions (already in ci.yml)
+
+Add your PyPI token to GitHub:
+  Repository → Settings → Secrets → Actions → New secret
+  Name: PYPI_API_TOKEN
+  Value: your-token
+
+Now every `git push --tags` auto-publishes to PyPI!

local_persona_memory-0.2.0/README.md

@@ -0,0 +1,118 @@
+# local-persona-memory
+
+> Long-term personalized memory for ANY local LLM running via Ollama.
+
+Your AI assistant forgets everything when the session ends. This library fixes that — permanently, privately, and with zero cloud dependency.
+
+## What it solves
+
+Most RAG libraries are built for searching documents. This library is built for **remembering people**. It stores user preferences, facts, skills, and goals, then injects the most relevant memories into every LLM response automatically.
+
+## Supported models
+
+Works with **any model in the Ollama library**:
+
+| Use case | Recommended model |
+|---|---|
+| General assistant | `llama3`, `llama3.1`, `mistral` |
+| Fast / lightweight | `phi3`, `gemma2:2b`, `tinyllama` |
+| Coding assistant | `codellama`, `deepseek-coder` |
+| Multilingual | `qwen2`, `qwen2.5` |
+| Reasoning | `deepseek-r1`, `qwen2.5:14b` |
+
+## Install
+
+```bash
+pip install local-persona-memory
+```
+
+**Prerequisites:**
+1. [Install Ollama](https://ollama.com)
+2. Pull a model and the embedding model:
+   ```bash
+   ollama pull llama3
+   ollama pull nomic-embed-text
+   ```
+3. Run `ollama serve` (or open the Ollama app)
+
+## Quick start
+
+```python
+from local_persona_memory import PersonaMemoryManager
+
+# Works with any Ollama model
+mem = PersonaMemoryManager(user_id="alice", model="llama3")
+
+# Store memories
+mem.remember("Alice is a Python developer building AI tools")
+mem.remember("Alice prefers concise answers and code examples")
+
+# Learn from documents
+mem.ingest_pdf("notes.pdf")
+
+# Chat with automatic memory context
+response = mem.chat("What should I work on today?")
+print(response)
+
+# Inspect stored memories
+print(f"Stored {mem.memory_count()} memories")
+```
+
+## Advanced usage
+
+```python
+from local_persona_memory import PersonaMemoryManager, LLMConfig, MemoryConfig, MemoryCategory
+
+mem = PersonaMemoryManager(
+    user_id="bob",
+    llm_config=LLMConfig(
+        model="mistral",         # any Ollama model
+        temperature=0.4,
+        context_window=8192,     # increase for larger models
+    ),
+    memory_config=MemoryConfig(
+        top_k_memories=8,        # retrieve more memories per query
+        chunk_size=512,          # PDF chunk size in characters
+        similarity_threshold=0.3,
+        embedding_model="nomic-embed-text",
+    ),
+)
+
+# Categorise memories for better filtering
+mem.remember("Bob knows Rust and Go", category=MemoryCategory.SKILL)
+mem.remember("Bob wants to build a CLI tool", category=MemoryCategory.GOAL)
+
+# Recall with category filter
+skill_memories = mem.recall("programming languages", category=MemoryCategory.SKILL)
+```
+
+## How it works
+
+```
+User message
+     │
+     ▼
+[Embed with nomic-embed-text]
+     │
+     ▼
+[ChromaDB similarity search] ──► Top-K relevant memories
+     │
+     ▼
+[Build prompt: system + memories + message]
+     │
+     ▼
+[Generate with Ollama model]
+     │
+     ▼
+Personalised response
+```
+
+Memories persist to `~/.local_persona_memory/` between sessions. Each user gets an isolated ChromaDB collection.
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md). Open an issue first for large changes.
+
+## License
+
+MIT

local_persona_memory-0.2.0/examples/basic_usage.py

@@ -0,0 +1,39 @@
+"""
+examples/basic_usage.py
+-----------------------
+Run this AFTER:
+  1. Installing Ollama: https://ollama.com
+  2. Pulling models:
+       ollama pull llama3
+       ollama pull nomic-embed-text
+  3. pip install local-persona-memory
+"""
+
+from local_persona_memory import PersonaMemoryManager, MemoryCategory
+
+# ── Works with ANY Ollama model ──────────────────────────────────────────────
+# Replace "llama3" with: mistral, phi3, gemma2, qwen2, deepseek-r1, etc.
+mem = PersonaMemoryManager(user_id="alice", model="llama3")
+
+# ── Store memories ───────────────────────────────────────────────────────────
+mem.remember("Alice is a software developer specialising in Python and AI")
+mem.remember("Alice prefers dark mode in all her editors and tools")
+mem.remember("Alice is building a RAG-based AI assistant as a side project")
+mem.remember("Alice's goal is to publish an open source library on PyPI",
+             category=MemoryCategory.GOAL)
+
+# ── Learn from a PDF ─────────────────────────────────────────────────────────
+# mem.ingest_pdf("path/to/your_document.pdf")
+
+# ── Chat with memory context ─────────────────────────────────────────────────
+response = mem.chat("What should I focus on this week?")
+print("Response:", response)
+
+# ── Inspect memories ─────────────────────────────────────────────────────────
+print(f"\nTotal memories: {mem.memory_count()}")
+
+results = mem.recall("programming preferences")
+for r in results:
+    print(f"  [{r.similarity_score:.2f}] {r.memory.text}")
+
+print(repr(mem))

local_persona_memory-0.2.0/examples/multi_model_demo.py

@@ -0,0 +1,38 @@
+"""
+examples/multi_model_demo.py
+-----------------------------
+Shows how to use different Ollama models for the same user.
+Demonstrates model-agnostic design.
+"""
+
+from local_persona_memory import PersonaMemoryManager, LLMConfig, MemoryConfig
+
+# Same user_id = same memories, different model for generation
+phi3_assistant = PersonaMemoryManager(
+    user_id="bob",
+    llm_config=LLMConfig(model="phi3", temperature=0.3),
+)
+
+llama_assistant = PersonaMemoryManager(
+    user_id="bob",
+    llm_config=LLMConfig(model="llama3", temperature=0.5),
+)
+
+mistral_assistant = PersonaMemoryManager(
+    user_id="bob",
+    llm_config=LLMConfig(model="mistral", temperature=0.4),
+)
+
+# Store once — all assistants share the same ChromaDB
+phi3_assistant.remember("Bob is learning Rust for systems programming")
+
+# Ask the same question with different models
+question = "What is Bob working on and what advice would you give?"
+print("=== phi3 response ===")
+print(phi3_assistant.chat(question))
+
+print("\n=== llama3 response ===")
+print(llama_assistant.chat(question))
+
+print("\n=== mistral response ===")
+print(mistral_assistant.chat(question))