widemem-ai 1.3.0__tar.gz

widemem_ai-1.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug Report
+about: Something isn't working as expected
+title: "[Bug] "
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear description of what went wrong.
+
+**To reproduce**
+```python
+# Minimal code to reproduce the issue
+```
+
+**Expected behavior**
+What you expected to happen.
+
+**Actual behavior**
+What actually happened. Include the full error traceback if applicable.
+
+**Environment**
+- Python version:
+- widemem version:
+- OS:
+- LLM provider:
+- Vector store:

widemem_ai-1.3.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: "[Feature] "
+labels: enhancement
+assignees: ''
+---
+
+**Problem**
+What problem does this solve? Why is it needed?
+
+**Proposed solution**
+How should it work? Include code examples if possible.
+
+**Alternatives considered**
+Any other approaches you've thought about.

widemem_ai-1.3.0/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+## What
+
+Brief description of the change.
+
+## Why
+
+Why is this change needed?
+
+## How
+
+How does it work? Any design decisions worth noting?
+
+## Checklist
+
+- [ ] Tests added/updated
+- [ ] All tests pass (`pytest`)
+- [ ] Linting passes (`ruff check .`)
+- [ ] CHANGELOG.md updated (if user-facing change)

widemem_ai-1.3.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "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
+        run: ruff check widemem/ tests/
+
+      - name: Test
+        run: pytest tests/ -v

widemem_ai-1.3.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+.env
+.env.*
+*.key
+credentials.json
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+
+*.db
+*.faiss
+state.json
+
+.venv/
+venv/
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store

widemem_ai-1.3.0/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.3.0] - 2026-03-09
+
+### Added
+
+- **Retry/backoff on LLM calls** — All LLM providers now retry up to 3 times with exponential backoff on transient errors (network, rate limits). `ProviderError` is not retried.
+- **Memory TTL** — `MemoryConfig(ttl_days=30)` auto-expires memories older than N days at search time. No background jobs needed.
+- **Score breakdown** — `MemorySearchResult` exposes `similarity_score`, `temporal_score`, `importance_score`, and `final_score` for debugging and transparency.
+- **Batch add** — `memory.add_batch(["text1", "text2", ...])` processes multiple texts in one call.
+- **Memory count** — `memory.count(user_id="alice")` returns total memory count with optional filters.
+- **Export/import JSON** — `memory.export_json()` and `memory.import_json(data)` for backup, restore, and migration. Import skips existing IDs.
+- 14 new tests (140 total)
+
+## [1.2.0] - 2026-03-08
+
+### Fixed
+
+- **Invalid default LLM model** — Changed default from non-existent `gpt-4.1-nano` to `gpt-4o-mini`
+- **Negative fact_index exploit** — Conflict resolver now rejects negative indices from LLM responses instead of silently wrapping via Python negative indexing
+- **Duplicate fact_index processing** — If LLM returns the same fact_index twice with different actions, only the first is processed
+- **Missing fact_index double-add** — Facts with missing `fact_index` in LLM response no longer get added twice (once from LLM action, once from fallback)
+- **Unbounded top_k** — `search(top_k=...)` now capped at 1000 to prevent memory exhaustion
+
+### Added
+
+- 3 new tests for conflict resolver edge cases (negative index, duplicate index, missing index)
+
+## [1.1.0] - 2026-03-08
+
+### Added
+
+- **YMYL two-tier confidence system** — Strong patterns (multi-word) get full treatment (importance floor 8.0, decay immunity, forced active retrieval). Weak patterns (single keyword) get moderate boost only. Prevents false positives like "bank of the river".
+- **YMYL documentation** — `YMYL.md` with full explanation of the two-tier system, examples, flow diagram, and limitations
+- **Duplicate content detection** — Content hash checked before insert, prevents identical memories from being stored
+- **list_all() on vector stores** — Proper metadata-based listing (FAISS + Qdrant) replaces zero-vector search hack in hierarchy
+- **End-to-end test script** — `scripts/e2e_test.py` for real OpenAI integration testing
+- **Resource cleanup** — `WideMemory` supports context manager (`with` statement), `close()`, and `__del__` for proper SQLite cleanup
+- **Thread safety** — Pipeline operations protected by threading lock for concurrent access
+- **Embedding dimension validation** — FAISS rejects vectors with wrong dimensions instead of silently corrupting
+- **Conflict resolver fallback** — Bad LLM JSON gracefully falls back to ADD all facts instead of crashing
+
+### Fixed
+
+- **YMYL regex case sensitivity** — Patterns with mixed case (IRS, MRI, W-2) now match correctly against lowercased text via `re.IGNORECASE`
+- **Zero-vector search hack** — Hierarchy manager now uses `list_all()` instead of searching with a zero vector
+
+## [1.0.0] - 2026-03-08
+
+### Added
+
+- **Core memory system** — `WideMemory` with add, search, get, delete, and history
+- **Batch conflict resolution** — Single LLM call resolves all new facts against existing memories (ADD/UPDATE/DELETE/NONE)
+- **Importance scoring** — Facts rated 1-10 at extraction time, normalized into combined scoring
+- **Time decay** — Four decay functions: exponential, linear, step, none
+- **Combined scoring** — `final_score = similarity * weight + importance * weight + recency * weight`
+- **Hierarchical memory** — Three-tier system (facts, summaries, themes) with automatic query routing and fallback chain
+- **Active retrieval** — Contradiction and ambiguity detection with clarification callbacks
+- **Self-supervised extraction** — SQLite-backed training data collector, small model fallback chain, training script
+- **Topic weights** — Configurable boost/suppress multipliers for retrieval, custom extraction hints
+- **Temporal search** — Time-range filters (time_after, time_before) on search
+- **History audit trail** — SQLite log of all add/update/delete operations
+- **Persistent FAISS** — Save/load to disk via `VectorStoreConfig.path`
+- **LLM providers** — OpenAI, Anthropic Claude, Ollama
+- **Embedding providers** — OpenAI, sentence-transformers (local)
+- **Vector store providers** — FAISS (local), Qdrant (local or cloud)
+- **UUID-to-integer ID mapping** — Prevents LLM hallucination of invalid memory IDs during conflict resolution
+- **MD5 content hashing** — Skips no-op updates when content hasn't changed
+- **Open source release** — README, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, LICENSE (Apache 2.0), GitHub templates, CI workflow
+- 126 tests, all passing

widemem_ai-1.3.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+**Examples of behavior that contributes to a positive environment:**
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+**Examples of unacceptable behavior:**
+
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project maintainer at **radu@cioplea.com**. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

widemem_ai-1.3.0/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to widemem
+
+Thanks for considering a contribution. Here's how to get started.
+
+## Setup
+
+```bash
+git clone https://github.com/remete618/widemem-ai.git
+cd widemem
+python3 -m pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+pytest
+```
+
+All tests use mocks — no API keys or external services needed.
+
+## Code style
+
+- We use [ruff](https://github.com/astral-sh/ruff) for linting and formatting
+- Run `ruff check .` and `ruff format .` before submitting
+- No docstrings or comments unless the logic isn't self-evident
+- No type stubs or backwards-compatibility shims — just change the code
+- Keep it simple. If three lines work, don't write an abstraction
+
+## Pull requests
+
+1. Fork the repo and create a branch from `main`
+2. Write tests for any new functionality
+3. Make sure all tests pass (`pytest`)
+4. Make sure linting passes (`ruff check .`)
+5. Keep PRs focused — one feature or fix per PR
+6. Write a clear PR description explaining what and why
+
+## What we're looking for
+
+- Bug fixes with a test that reproduces the bug
+- New provider implementations (LLM, embedding, vector store)
+- Performance improvements with benchmarks
+- Documentation improvements
+
+## What we're not looking for (yet)
+
+- Major architectural changes without prior discussion — open an issue first
+- Features that add complexity without clear user value
+- Dependencies on large frameworks or libraries
+
+## Reporting bugs
+
+Open a GitHub issue with:
+- What you expected to happen
+- What actually happened
+- Steps to reproduce
+- Python version and OS
+
+## Code of Conduct
+
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Be decent.

widemem_ai-1.3.0/LICENSE

@@ -0,0 +1,15 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.