highhxpack 0.1.0__tar.gz

highhxpack-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.env.*
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+# Local memory databases must never be committed.
+*.db
+*.db-wal
+*.db-shm
+*.sqlite3
+*.log
+.tox/
+.nox/
+.idea/
+.vscode/

highhxpack-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/). Before 1.0.0, minor releases may contain
+breaking changes; they are always listed under **Changed** or **Removed**.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-26
+
+First public release.
+
+### Added
+
+- `Memory` API: `remember`, `ingest`, `recall`, `search`, `get`, `update`, `forget`,
+  `restore`, `delete`, `list`, `count`, `clear`, `stats`, `inspect`, `users`,
+  `history`, `conflicts`, `resolve_conflict`, `consolidate`, `reindex`, `export`,
+  `import_`, `resolve_id`, and the `graph` property.
+- SQLite storage with WAL mode, transactions, versioned migrations, owner-only file
+  permissions and safe concurrent first-time initialization.
+- Keyword (BM25), semantic (cosine) and hybrid retrieval with a transparent,
+  centrally configured ranking (`ScoringConfig`) and per-result score breakdowns.
+- Embedding providers: deterministic local hashing embedding (default),
+  sentence-transformers, Ollama, OpenAI and callables.
+- LLM providers: Ollama, OpenAI and callables (all optional).
+- Rule-based and LLM-based extraction of facts, preferences, goals, decisions,
+  relationships and events; entity recognition.
+- Exact and near-duplicate detection with reinforcement; claim-based conflict
+  detection with `supersede`/`keep_both` policies and full history.
+- Consolidation: expiry archiving, duplicate merging, missed-conflict resolution and
+  optional summaries.
+- Lightweight per-user knowledge graph.
+- JSON export/import with strict validation.
+- `highhxpack` CLI: `init`, `config`, `remember`, `recall`, `search`, `memories`,
+  `inspect`, `history`, `forget`, `restore`, `conflicts`, `resolve`, `consolidate`,
+  `stats`, `export`, `import`, with `--json` output and documented exit codes.
+- Integrations: `ChatMemory`/`format_memories`, LangChain and LlamaIndex retrievers.
+- Graceful degradation: hybrid retrieval falls back to keyword relevance if the
+  embedding provider fails; LLM providers are created on first use.
+- Configuration via file, environment variables and arguments with documented
+  precedence.
+
+[Unreleased]: https://github.com/highhxpack/highhxpack/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/highhxpack/highhxpack/releases/tag/v0.1.0

highhxpack-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,42 @@
+# Code of Conduct
+
+## Our pledge
+
+We as members, contributors and maintainers pledge to make participation in this
+project a harassment-free experience for everyone, regardless of age, body size,
+visible or invisible 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:
+
+- demonstrating empathy and kindness toward other people;
+- being respectful of differing opinions, viewpoints and experiences;
+- giving and gracefully accepting constructive feedback;
+- taking responsibility for our mistakes and learning from them;
+- focusing on what is best for the community.
+
+Examples of unacceptable behavior:
+
+- sexualized language or imagery, and unwelcome sexual attention or advances;
+- trolling, insulting or derogatory comments, and personal or political attacks;
+- public or private harassment;
+- publishing others' private information without their explicit permission;
+- other conduct which could reasonably be considered inappropriate in a professional
+  setting.
+
+## Enforcement
+
+Maintainers are responsible for clarifying and enforcing these standards and may
+remove, edit or reject contributions that do not align with this Code of Conduct.
+Report unacceptable behavior privately to the maintainers through the repository's
+security/advisory contact or by direct message to a maintainer. All reports will be
+reviewed and investigated promptly and fairly, and the privacy of reporters will be
+respected.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

highhxpack-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to HighHXPack
+
+Thanks for your interest! Bug reports, documentation fixes and pull requests are all
+welcome.
+
+## Development setup
+
+```bash
+git clone https://github.com/highhxpack/highhxpack
+cd highhxpack
+uv sync                 # or: python -m venv .venv && pip install -e . --group dev
+uv run pre-commit install
+```
+
+## Checks
+
+Run these before opening a pull request; CI runs the same commands.
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest --cov                 # all tests; fails below 90% coverage
+uv run pytest -m "not slow"         # quicker loop
+uv run python -m build && uv run twine check dist/*   # packaging (optional)
+```
+
+## Guidelines
+
+- **Tests first.** Every feature needs tests; every bug fix needs a regression test
+  that fails without the fix.
+- **No new required dependencies.** The core must keep working with the standard
+  library only. Optional integrations go behind an extra and a lazy import that raises
+  `ProviderNotAvailableError` with install instructions.
+- **Public API** is what `highhxpack/__init__.py` exports. Changing it needs a
+  CHANGELOG entry; breaking changes need a deprecation path where possible.
+- **Errors** raise a `HighHXPackError` subclass with a message, and ideally a reason
+  and a hint.
+- **No magic numbers** in ranking or policies: put tunables in a config dataclass.
+- **Schema changes** are new migrations in `storage/migrations.py`; never edit a
+  released migration.
+- **Privacy**: never log memory content or secrets at INFO level or above, and never
+  send data to a network service unless the user configured it.
+- Keep documentation in `docs/` and `README.md` in sync with the code.
+
+## Releasing (maintainers)
+
+1. Update `src/highhxpack/__version__.py` and move `Unreleased` entries in
+   `CHANGELOG.md` under the new version.
+2. Merge to `main`, tag `vX.Y.Z` and publish a GitHub release. The `publish` workflow
+   builds, checks and uploads to PyPI through trusted publishing.
+
+By contributing you agree that your contributions are licensed under the MIT License
+and that you will follow the [Code of Conduct](CODE_OF_CONDUCT.md).

highhxpack-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HighHXPack contributors
+
+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.

highhxpack-0.1.0/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: highhxpack
+Version: 0.1.0
+Summary: Local-first memory and context engine for AI applications, agents, and developer tools.
+Project-URL: Homepage, https://github.com/highhxpack/highhxpack
+Project-URL: Documentation, https://github.com/highhxpack/highhxpack/tree/main/docs
+Project-URL: Repository, https://github.com/highhxpack/highhxpack
+Project-URL: Issues, https://github.com/highhxpack/highhxpack/issues
+Project-URL: Changelog, https://github.com/highhxpack/highhxpack/blob/main/CHANGELOG.md
+Author: HighHXPack contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,context,llm,local-first,memory,retrieval,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.3; extra == 'all'
+Requires-Dist: llama-index-core>=0.11; extra == 'all'
+Requires-Dist: openai>=1.40; extra == 'all'
+Requires-Dist: sentence-transformers>=2.7; extra == 'all'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.11; extra == 'llamaindex'
+Provides-Extra: ollama
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'
+Provides-Extra: sentence-transformers
+Requires-Dist: sentence-transformers>=2.7; extra == 'sentence-transformers'
+Description-Content-Type: text/markdown
+
+# HighHXPack
+
+**A local-first memory and context engine for AI applications, agents and developer tools.**
+
+HighHXPack gives your chatbot, agent or tool a long-term memory: it stores what users
+tell it, recognizes facts and preferences, avoids duplicates, keeps track of
+information that changes over time, and retrieves the most relevant memories for a
+prompt — all on the local machine, in a single SQLite file, with **no required
+dependencies, API keys, or cloud services**.
+
+```python
+from highhxpack import Memory
+
+memory = Memory()
+memory.remember(user_id="user_123", content="I prefer Python for AI development.")
+
+results = memory.recall(user_id="user_123", query="What language do I prefer for AI?")
+print(results[0].content)  # I prefer Python for AI development.
+```
+
+> Status: **alpha (0.1.0)**. The public API is documented and tested, but may
+> still change before 1.0; changes are recorded in [CHANGELOG.md](CHANGELOG.md).
+
+## Why HighHXPack?
+
+LLM applications forget everything between sessions. Common fixes send user data to a
+hosted memory service or require a vector database. HighHXPack is a library instead:
+
+- **Local and private by default** — data lives in a SQLite file you control.
+  Nothing leaves the machine unless you configure a remote provider.
+- **Zero required dependencies** — the core uses only the Python standard library.
+- **More than a vector store** — deduplication, conflict handling with history,
+  importance/recency ranking, extraction, consolidation and a small knowledge graph.
+- **Transparent ranking** — every result carries a score breakdown; all weights live
+  in one configuration object.
+- **Pluggable** — bring your own embedding model, LLM, or storage backend.
+
+## Installation
+
+```bash
+pip install highhxpack
+```
+
+Requires Python 3.11+. Optional extras add third-party providers:
+
+```bash
+pip install "highhxpack[openai]"                 # OpenAI embeddings / LLM
+pip install "highhxpack[sentence-transformers]"  # local neural embeddings
+pip install "highhxpack[langchain]"              # LangChain retriever
+pip install "highhxpack[llamaindex]"             # LlamaIndex retriever
+pip install "highhxpack[ollama]"                 # no extra packages; Ollama uses HTTP
+pip install "highhxpack[all]"
+```
+
+## Five-minute quickstart
+
+```python
+from highhxpack import Memory
+
+with Memory() as memory:  # ~/.local/share/highhxpack/memory.db on Linux
+    memory.remember("alice", "I prefer Python for AI development.")
+    memory.remember("alice", "My favorite editor is Neovim.", importance=0.8)
+    memory.remember("alice", "Temporary door code is 4321", ttl="1d")  # expires
+
+    # Duplicates reinforce the existing memory instead of piling up.
+    result = memory.remember("alice", "User prefers Python for AI development")
+    print(result.action)  # reinforced
+
+    # Changing information: the old statement is superseded, not deleted.
+    memory.remember("alice", "I live in Paris")
+    update = memory.remember("alice", "I live in Berlin")
+    print(update.superseded_ids)  # ('<id of the Paris memory>',)
+
+    # Ranked retrieval with an explanation of every score.
+    for r in memory.recall("alice", "where do I live?", limit=5):
+        print(f"{r.score:.2f} {r.content}  relevance={r.breakdown.relevance:.2f}")
+
+    # Extract memorable statements from free text (offline, rule-based).
+    memory.ingest(
+        "alice",
+        "I've been using Python for ML for years, "
+        "but I prefer C++ for competitive programming. How are you?",
+    )
+    print(memory.graph.neighbors("alice", "user"))  # ['C++', 'Python']
+
+    # Everything else
+    memory.search("python", user_id="alice", status="any")  # includes history
+    memory.list("alice", memory_type="preference")
+    memory.history(update.id)  # every version/change
+    memory.consolidate("alice", dry_run=True)  # merge dupes, apply policy
+    memory.export("alice.json", user_id="alice")
+    memory.stats()
+```
+
+The full public API: `remember`, `ingest`, `recall`, `search`, `get`, `update`,
+`forget`, `restore`, `delete`, `list`, `count`, `clear`, `stats`, `inspect`,
+`users`, `history`, `conflicts`, `resolve_conflict`, `consolidate`, `reindex`,
+`export`, `import_`, and the `graph` property. See [docs/api](docs/api/memory.md).
+
+## CLI
+
+```bash
+highhxpack init                         # data directory, config file, database
+highhxpack remember "I use Python"
+highhxpack remember --extract "I prefer Rust, but I use Go at work."
+highhxpack recall "programming language" --explain
+highhxpack search "python" --status any --json
+highhxpack memories                     # list (alias: list)
+highhxpack inspect alice                # summary + knowledge graph of a user
+highhxpack history 1a2b3c4d             # a memory and its change history
+highhxpack forget 1a2b3c4d              # archive (restorable); --permanent to erase
+highhxpack conflicts                    # contradictions awaiting a decision
+highhxpack consolidate --dry-run
+highhxpack stats
+highhxpack export backup.json
+highhxpack import backup.json
+highhxpack config                       # effective configuration (secrets masked)
+highhxpack --help / --version
+```
+
+Every command accepts `--user`, `--db`, `--config`, `--json` and `--no-color`.
+Memory ids can be abbreviated to a unique prefix. Exit codes: `0` success, `1` error,
+`2` invalid input, `3` not found, `130` interrupted. Errors are printed as a message,
+reason and hint — never as a traceback.
+
+## Architecture
+
+```text
+Memory (public API)
+ ├── MemoryManager ─ write path: validation → dedup → conflicts → index → history
+ │     ├── consolidation/  deduplication · conflict · importance · summarization
+ │     └── extraction/     rule-based or LLM extraction of facts, preferences, …
+ ├── Retriever ─ keyword (BM25) + semantic (cosine) → hybrid ranking
+ ├── KnowledgeGraph ─ user --prefers--> C++
+ ├── EmbeddingProvider ─ hashing (default) · sentence-transformers · Ollama · OpenAI · custom
+ ├── LLMProvider ─ none (default) · Ollama · OpenAI · custom
+ └── StorageBackend ─ SQLiteStorage (default, WAL, migrations) · your own
+```
+
+Details: [docs/concepts/architecture.md](docs/concepts/architecture.md).
+
+## How it works
+
+**Memories** have a type (`fact`, `preference`, `event`, `goal`, `relationship`,
+`knowledge`, `conversation`, `decision`, or any lower-case identifier you choose),
+importance, confidence, source, metadata, optional expiry, a version and a status:
+`active` (current belief), `superseded` (replaced by newer information),
+`merged` (folded into a duplicate), or `archived` (forgotten, restorable).
+
+**Deduplication**: identical content (ignoring case/punctuation) and near-duplicates
+(canonical token overlap, e.g. "User likes Python" ≈ "User prefers Python") reinforce
+the existing memory. Statements with opposite polarity are never merged.
+
+**Conflicts**: statements that fill the same *slot* with different values
+("I prefer Java" → "I prefer Python", "I live in Paris" → "I live in Berlin") are
+detected. Under the default `supersede` policy the newer statement becomes current
+only if it is at least as confident; the older one is kept with status `superseded`
+and a conflict record explains why. Otherwise both stay active and the conflict is
+left open for you to resolve. HighHXPack never guesses which statement is true.
+
+**Ranking** (all constants in `ScoringConfig`):
+
+```text
+relevance = weighted mean of keyword (BM25, normalized) and semantic (cosine) scores
+final     = relevance × (0.60 + 0.15·importance + 0.10·recency + 0.10·confidence + 0.05·frequency)
+```
+
+A memory that does not match the query scores 0 however important it is. See
+[docs/concepts/retrieval.md](docs/concepts/retrieval.md).
+
+## Storage behavior
+
+- One SQLite file, by default in the platform data directory
+  (`~/.local/share/highhxpack/memory.db`, `~/Library/Application Support/highhxpack/`
+  on macOS, `%LOCALAPPDATA%\highhxpack\` on Windows), or `Memory("path/to/file.db")`.
+- WAL mode, explicit transactions, versioned migrations, indexes, and a clean
+  checkpoint on close. Safe for several threads and several processes.
+- The database directory is created with mode `0700` and the file `0600` (POSIX).
+- `Memory(":memory:")` gives a throw-away in-memory store.
+
+## Embeddings and LLM providers
+
+Embeddings and LLMs are **optional**.
+
+| Setting | Default | Options |
+|---|---|---|
+| `embedding_provider` | `hashing` (local, lexical, no downloads) | `none`, `sentence-transformers`, `ollama`, `openai` |
+| `llm_provider` | `none` | `ollama`, `openai` |
+
+The default hashing embedding is deterministic and offline. It captures shared words,
+stems and sub-word fragments, but not synonyms; for meaning-based search use
+`sentence-transformers` or Ollama. LLMs are used only for `extractor = "llm"` and
+LLM-written summaries. Custom providers:
+
+```python
+from highhxpack import CallableEmbedding, CallableProvider, Memory
+
+memory = Memory(
+    embedder=CallableEmbedding(my_embed_fn, name="my-model-v1"),  # fn(list[str]) -> vectors
+    llm=CallableProvider(my_complete_fn),  # fn(prompt) -> str
+)
+```
+
+Missing optional packages produce an error that says exactly what to install.
+
+## Configuration
+
+Precedence (lowest → highest): built-in defaults → config file
+(`<home>/config.toml` or `$HIGHHXPACK_CONFIG`) → `HIGHHXPACK_*` environment variables →
+explicit Python arguments / CLI options. `highhxpack config` prints the result.
+API keys are **never** read from the config file; set `OPENAI_API_KEY` instead.
+See [docs/concepts/configuration.md](docs/concepts/configuration.md).
+
+## Privacy and security
+
+- All data stays on your machine unless you configure `ollama` on a remote host or
+  `openai`; only then is the text being embedded/processed sent to that endpoint.
+- Secrets are never logged or printed; the config file cannot contain API keys.
+- Input is validated; control characters are stripped; SQL uses bound parameters.
+- Imports accept only HighHXPack's JSON format (never pickle), validate every record,
+  and enforce a size limit. Exports are written atomically with mode `0600`.
+- `delete()`/`clear()` permanently erase memories including their history.
+
+See [SECURITY.md](SECURITY.md) and [docs/concepts/privacy.md](docs/concepts/privacy.md).
+
+## Examples
+
+- [examples/basic.py](examples/basic.py) — store, recall, update, forget
+- [examples/chatbot.py](examples/chatbot.py) — memory loop for a chatbot
+- [examples/agent_memory.py](examples/agent_memory.py) — metadata, TTL, graph, consolidation, export
+- [examples/local_llm.py](examples/local_llm.py) — Ollama extraction and summaries
+
+## Development
+
+```bash
+git clone https://github.com/highhxpack/highhxpack
+cd highhxpack
+uv sync                     # or: python -m venv .venv && pip install -e . --group dev
+uv run pytest --cov         # unit + integration tests, 90% coverage floor
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+uv run python benchmarks/benchmark_retrieval.py
+```
+
+Benchmarks print measurements for your hardware; no numbers are claimed here.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[Code of Conduct](CODE_OF_CONDUCT.md). Report security issues privately as described
+in [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)