pmb-ai 0.1.0__tar.gz

pmb_ai-0.1.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to PMB are documented here.
+
+## [Unreleased]
+
+### Hardening pass 2 - lazy LanceDB + use-case clarity
+
+- **`pmb stats` and friends now run in ~1 s (was ~14 s).** The single biggest user-facing cost was `import lancedb` itself: on Windows it pulls in pyarrow + torch and takes ~22 s to import. `HybridSearch.__init__` triggered that import for every CLI command, even ones that never touch vectors. Fix: `HybridSearch` defers `lancedb.connect(...)` and the table-open to a lazy `_table` property; `Engine.__init__` no longer eagerly calls `reload_bm25()`. The cost is now paid on the first `recall()` or write that actually needs vector search.
+- **README "What gets stored, when" gets a `Which features help which use case` table.** Honest mapping of feature flags to workloads (multi-hop, narrative, temporal, code, multilingual, etc.) - so contributors don't assume every feature must boost LoCoMo recall.
+- **All 88 core tests + 9 smoke tests still pass.**
+
+### Hardening pass 1 - import hygiene + test foundation
+
+- **Lazy top-level imports.** `import pmb` no longer pulls in LanceDB, sentence-transformers, numpy, rank_bm25, fastmcp, yaml, torch or transformers. Heavy attributes (`Engine`, `Workspace`, `detect_workspace`) are exposed via PEP 562 `__getattr__` and loaded on first access. Measured: bare `import pmb` is now **2.4 ms** (was ~14 s when the engine was eagerly imported). Same treatment applied to `pmb.core`.
+- **`tests/conftest.py`** added with shared fixtures (`tmp_pmb_home`, `tmp_workspace_dir`, `isolated_engine`) and a `sys.path` fallback so new tests don't need the boilerplate.
+- **`tests/test_lightweight_imports.py`** added - 9 smoke tests that spawn fresh interpreters and assert which heavy modules are loaded after specific imports. If a future change re-introduces an eager heavy import at `pmb/__init__.py` it will fail this suite.
+- **No behaviour change.** All 88 core tests (the `make test` set used in CI) still pass; `from pmb import Engine` still works.
+
+### Recall ablation findings + default changes
+
+Ran a full-system ablation across 19 retrieval components on LoCoMo conv-26/30/41 (see `scripts/benchmarks/ablation_full.py`). Key findings:
+
+- **`recall.typo_correction = True` was hurting recall by ~6.2 points.** The Levenshtein-≤2 fuzzy rewriter was "correcting" correctly-spelled tokens into similar-looking but wrong entity names. **Default flipped to `False`.** Existing per-workspace overrides are unaffected.
+- **BM25-heavy fusion outperformed the symmetric default.** `recall.bm25_weight` raised `0.5 -> 0.7`. Vector-only retrieval loses 18 points on this dataset; the embedding channel adds only marginal signal.
+- **Net effect on the full 10-conversation LoCoMo benchmark: 91.6 % -> 94.1 % evidence-recall@10** (+2.5 pp, every conversation improved, range now 91.2-96.2 %).
+- **Twelve of nineteen ablated features show 0.000 delta on LoCoMo:** tiers, causation walk, arc expansion, collapse-reflections, reflection-to-edges, predictive cache, code-AST, LRU cache, multi-entity bonus, PPR, adaptive routing, spreading activation, temporal. These are not removed - some are designed for long-term dynamics that LoCoMo doesn't probe - but the README and docs no longer claim they carry the benchmark number.
+- **Cross-encoder reranker (`recall.rerank = True`) regresses 17 points and adds 845 ms p50.** Recommendation removed from default setup; flag is still available as experimental.
+
+See `scripts/benchmarks/ablation_full.py` and `docs/HARDENING_NOTES.md` for the raw data and methodology.
+
+## [0.1.0] - Initial public release
+
+### Highlights
+
+- Single-file install: `pip install -e .` exposes `pmb` on `$PATH`.
+- 91.6 % evidence-recall@10 on LoCoMo full 10-conversation run (vs published mem0 / Letta / Zep numbers of 70-80 %).
+- 90-140 ms p50 recall latency, 2 ms async writes.
+- 13 semantic layers, 5 access paths, 3 tiers - every layer optional and configurable.
+- Web dashboard + 5-tab terminal TUI for inspection.
+- MCP server for Claude Code, Codex CLI, Cursor.
+- Optional Ollama integration for fully-local LLM ops (consolidation, dedup verify, pmb-chat).
+
+### Architecture decisions worth knowing
+
+- **Local-first.** SQLite + LanceDB on disk; no daemon, no service, no network.
+- **Lazy-by-default agent prompt.** PMB is OFF until an explicit trigger ("remember", personal fact, "what did I…"). General Q&A bypasses PMB entirely.
+- **Async writes (fire-and-forget MCP).** `record_batch` returns in ~2 ms; embedding + LanceDB indexing happen in a background thread.
+- **BM25 fallback for cold reads.** First `recall` after process start returns text-match results in ~100 ms while the sentence-transformers model finishes loading.
+- **Multi-layer dedup.** L1 exact (5 ms) + L2 cosine ≥ 0.92 (50 ms) at write time; L2.5 borderline queue for LLM-verified merges; L3 dashboard review tab for ambiguous pairs.
+- **Conservative defaults.** False-merge risk minimised: never merges across event types, threshold 0.92 leaves a safe gap.
+
+### Tools and surfaces
+
+- `pmb tui` - five tabs: Memory, Recall, Stats, Dedup, Tune
+- `pmb dashboard` - HTTP dashboard on :8765 with Graph, Events, Performance, Duplicates, Recall Debug
+- `pmb tune` - settings-only TUI (67 knobs)
+- `pmb ollama` - health, install/use models, smoke test
+- `pmb connect codex | claude | cursor` - wires MCP into the agent's config and rules file
+- `pmb dedupe` / `pmb regraph` / `pmb prune-graph` - maintenance ops
+
+### Settings (67 across 9 categories)
+
+`recall` (36), `consolidate` (9), `dedup` (6), `chat` (5), `decay` (3), `embedding` (3), `feedback` (2), `ollama` (2), `mcp` (1). All exposed in TUI Tune tab, CLI `pmb config`, and dashboard.
+
+### Known limits
+
+- Single-machine. No cross-device sync.
+- Cold first recall after process start blocks on model load if the BM25 fallback path is disabled.
+- Code-AST extraction is Python-only (regex fallback for broken / partial code).
+- Dashboard and TUI assume one workspace at a time.

pmb_ai-0.1.0/CITATION.cff

@@ -0,0 +1,23 @@
+cff-version: 1.2.0
+title: PMB - Personal Memory Brain
+message: >-
+  If you use PMB in published research or build on top of it,
+  please cite this software.
+type: software
+authors:
+  - name: PMB contributors
+repository-code: https://github.com/yourname/pmb
+abstract: >-
+  Local-first persistent memory for AI coding agents over MCP.
+  Hybrid BM25+vector retrieval with SQLite + LanceDB storage.
+  Evidence-recall@10 on LoCoMo: 94.1% across the full 10-conversation
+  run with v0.1.0 defaults. Warm-recall p50 latency 65-195 ms;
+  no API keys required.
+keywords:
+  - mcp
+  - memory
+  - retrieval
+  - ai-agent
+  - rag
+license: Apache-2.0
+version: 0.1.0

pmb_ai-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,24 @@
+# Code of Conduct
+
+## In short
+
+Be respectful. Engage with the work, not the person. Disagree on technical grounds, document trade-offs, move on.
+
+## Specifics
+
+- Use the issue tracker for bugs and concrete proposals, not for venting.
+- "It feels slow / wrong / weird" is not a useful report - include timings, repros, version info.
+- Code review is about the code. Personal attacks, slurs, harassment of any kind - instant ban.
+- English is the working language. Other languages welcome in private discussion but PRs and issues should be in English so anyone can participate.
+
+## Reporting issues with conduct
+
+Email the maintainer or open a private GitHub conversation. We will read every report.
+
+## Enforcement
+
+The maintainers may remove comments, close issues, or ban contributors who repeatedly act against this code. There is no formal three-strike system - egregious behaviour gets a ban on the first occurrence.
+
+---
+
+Adapted in spirit from the [Contributor Covenant](https://www.contributor-covenant.org/), kept short on purpose.

pmb_ai-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to PMB
+
+Thanks for your interest. PMB is intentionally small and opinionated; here is what helps and what doesn't.
+
+## Development setup
+
+```bash
+git clone <repo-url> pmb
+cd pmb
+python -m venv .venv
+source .venv/bin/activate            # Windows: .venv\Scripts\activate
+pip install -e .
+pip install textual                  # for the TUI
+pip install pytest                   # for tests
+```
+
+Verify:
+
+```bash
+make test        # 88 passed in ~80s — the same set CI runs
+make test-smoke  # 9 passed in ~5s   — import-weight regression tests
+```
+
+## Running tests
+
+**Use `make test`, not `pytest tests/` directly.** The full pytest target (`pytest tests/`) has a known deadlock: several modules trigger parallel `huggingface_hub` model downloads against the same on-disk cache, and the second downloader blocks waiting for a lock the first one hasn't released. Symptom: pytest hangs forever on collection.
+
+| Target | What it runs | When to use |
+|---|---|---|
+| `make test` (= `make test-core`) | 8 deterministic files from `.github/workflows/ci.yml`, 88 tests | Default during development; matches CI |
+| `make test-smoke` | `tests/test_lightweight_imports.py`, 9 tests | After touching `pmb/__init__.py` or any module added to the lazy-attribute table |
+| `make test-all-WARN` | The full `tests/` directory | Only if your HF cache is already populated; otherwise it will hang |
+| `pytest tests/test_X.py` | One specific file | Reproducing a single failure |
+
+If you add a new test that depends on a HuggingFace download, please mark it (`@pytest.mark.heavy`, manual `pytest -k`) and document why - we'd rather not grow the deadlock surface.
+
+## Project layout
+
+```
+src/pmb/
+  core/             - engine, events, search, workspace, recall_cache
+  graph/            - entities, persons, store (SQLite-backed)
+  reasoning/        - facts, reflect, causation, arcs, temporal, dedup, typo_fix
+  mcp/              - FastMCP server, perf tracking, tools schema
+  dashboard/        - local web UI (HTTP, no framework)
+  cli/              - typer entry points (main, tui_*, ollama_cmd, connect)
+  agent_wrapper/    - pmb-chat (optional standalone chat loop)
+  health/           - consolidation, doctor checks
+  eval/             - LoCoMo judge helpers
+tests/              - pytest, no fixtures spanning files
+scripts/            - benchmarks, demos, profilers
+```
+
+## Where to add things
+
+| You want to… | Touch this |
+|---|---|
+| add a recall ranking signal | `core/engine.py` (search the `recall(` method, ~12 stages) |
+| change a tunable knob | `config.py` (single SCHEMA dict) |
+| add an MCP tool | `mcp/server.py` (decorate with `@mcp.tool()`) |
+| add a CLI command | `cli/main.py` |
+| add a dashboard tab | `dashboard/static/index.html` + a handler in `dashboard/server.py` |
+| add a TUI tab | `cli/tui_workspace.py` |
+
+## Code style
+
+- Keep modules focused. The recall pipeline is already large; do not add new top-level layers without a clear reason.
+- Public methods on `Engine` should be readable from a docstring alone.
+- All write-path additions must be sub-100 ms on warm cache. Profile before merging if you add embedding work.
+- Pure-Python where possible. PyTorch is fine (already a dep); avoid adding new heavy dependencies.
+
+## Tests
+
+- Unit tests live in `tests/`. They use temp workspaces (`tempfile.mkdtemp`); don't write to `~/.pmb/` from a test.
+- For features that touch recall scoring, add a test in `tests/test_graph.py` style that asserts ordering, not exact scores.
+- The full LoCoMo bench (`scripts/benchmark_locomo.py`) is the integration test for retrieval quality.
+
+## Pull requests
+
+- One concern per PR.
+- Include a short description of what changed and **a benchmark line** if recall accuracy or latency could be affected.
+- Updating the README's benchmark numbers is fine when you have new data - link to the run that produced them.
+
+## Hardening passes (style for cross-cutting refactors)
+
+If you are doing a sweeping technical-debt pass (lazy imports, exception handling, type annotations, etc.) please follow this protocol so it stays reviewable:
+
+1. **Phase 0 - inventory first.** Before changing anything, post the current state to the PR description: file/line numbers, what each call does, why it exists. For exception-handler changes specifically, see `docs/HARDENING_NOTES.md` for the categorisation we want to preserve.
+2. **One phase per commit.** Lazy imports, conftest, smoke tests, exception logging - each is its own commit so we can bisect a regression.
+3. **Run `make test` after every commit.** Not `make test-all-WARN`.
+4. **Behaviour-preserving by default.** If a change alters runtime behaviour (e.g. converting a silent fallback into an exception), call it out explicitly and add a test.
+5. **Update CHANGELOG.md.** Hardening counts as a real change; document the measurable effect (`import pmb` time, test count, etc.).
+
+## What we are not looking for
+
+- Multi-user, multi-device, cloud sync. PMB is single-user single-machine on purpose.
+- Frontend frameworks. The dashboard is plain HTML/JS; the TUI is textual. Keep it that way.
+- New embedding backends. We have sentence-transformers (default) and fastembed (optional). Adding a third needs a strong case.
+
+## Filing issues
+
+Useful issues include: a minimal repro (or a workspace dump), the version of PMB (`pip show pmb`), and what command/agent triggered it. "It feels slow" without timing data is harder to act on - `pmb tui` → `[3] Stats` shows the real numbers.
+
+## Licensing of contributions
+
+PMB is licensed under **Apache License 2.0** (see [`LICENSE`](LICENSE)).
+
+By submitting a pull request, you agree that your contribution is licensed under the same terms - this is the default behaviour spelled out in Apache 2.0 §5 ("Submission of Contributions"). No separate CLA, no sign-off chain. Just open the PR.
+
+If your contribution includes code or assets you did not write, list their origin and license in the PR description so we can add them to [`NOTICE`](NOTICE).

pmb_ai-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 PMB contributors
+
+   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.

pmb_ai-0.1.0/MANIFEST.in

@@ -0,0 +1,44 @@
+# Files to include in `python -m build` source distribution (sdist).
+# Wheel uses `pyproject.toml` setuptools.packages.find — this is just
+# for sdist completeness.
+
+include README.md
+include LICENSE
+include NOTICE
+include CHANGELOG.md
+include CITATION.cff
+include CODE_OF_CONDUCT.md
+include CONTRIBUTING.md
+include SECURITY.md
+include pyproject.toml
+include Makefile
+
+# Documentation
+recursive-include docs *.md
+# Logo + screenshots referenced by README.md (rendered on PyPI page)
+recursive-include docs/assets *.png *.css
+
+# Test files for downstream packagers who want to verify the install
+recursive-include tests *.py
+include tests/conftest.py
+
+# Package data
+recursive-include src/pmb py.typed
+recursive-include src/pmb/dashboard/static *
+
+# Exclude development artefacts
+global-exclude __pycache__
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude .DS_Store
+global-exclude Thumbs.db
+global-exclude *.swp
+global-exclude .gitignore
+prune .venv
+prune .git
+prune .github
+prune scripts/benchmarks/_test_*.py
+prune docs/assets/_capture_server.py
+prune docs/assets/_save_png.py
+prune docs/assets/*.html
+prune .claude

pmb_ai-0.1.0/Makefile

@@ -0,0 +1,76 @@
+.PHONY: help install dev test test-core test-smoke test-all-WARN lint format clean bench bench-quick tui dashboard
+
+help:
+	@echo "PMB development targets:"
+	@echo "  make install        - pip install -e ."
+	@echo "  make dev            - install + dev tools (pytest, ruff, textual)"
+	@echo ""
+	@echo "  make test           - alias for test-core (CI baseline, 88 tests, ~80s)"
+	@echo "  make test-core      - the 8 deterministic core test files from .github/workflows/ci.yml"
+	@echo "  make test-smoke     - lightweight import smoke tests only (~5s)"
+	@echo "  make test-all-WARN  - full pytest tests/  (KNOWN ISSUE: hangs on huggingface_hub parallel"
+	@echo "                        downloads when the embedding model isn't cached; only run if you"
+	@echo "                        have the HF cache populated)"
+	@echo ""
+	@echo "  make lint           - ruff check"
+	@echo "  make format         - ruff format"
+	@echo "  make clean          - remove build artefacts and __pycache__"
+	@echo "  make bench          - full LoCoMo benchmark (10 conversations, ~30 min)"
+	@echo "  make bench-quick    - quick smoke benchmark (3 conversations, ~3 min)"
+	@echo "  make tui            - launch terminal UI"
+	@echo "  make dashboard      - launch web dashboard on :8765"
+
+install:
+	pip install -e .
+
+dev:
+	pip install -e ".[dev]"
+
+# --------------------------------------------------------------------------
+# Tests. The default `test` target intentionally runs ONLY the 8 core files
+# used by CI. Running `pytest tests/` directly is known to deadlock on first
+# run because several test modules trigger parallel huggingface_hub model
+# downloads against the same cache directory. Until that is fixed, use:
+#   - `make test`        for the deterministic CI baseline
+#   - `make test-smoke`  for the import-weight smoke tests
+#   - `make test-all-WARN` only if your HF cache is already populated
+# --------------------------------------------------------------------------
+
+test: test-core
+
+test-core:
+	pytest tests/test_graph.py tests/test_persons.py tests/test_goals_chains.py \
+	       tests/test_fact_tree.py tests/test_recall_cache.py tests/test_config.py \
+	       tests/test_redact.py tests/test_causation.py -q
+
+test-smoke:
+	pytest tests/test_lightweight_imports.py -v
+
+test-all-WARN:
+	@echo "WARNING: full pytest is known to deadlock on parallel HF downloads."
+	@echo "         If this hangs >60s, Ctrl-C and run 'make test-core' instead."
+	pytest tests/ -q
+
+lint:
+	ruff check src/ tests/ scripts/
+
+format:
+	ruff format src/ tests/ scripts/
+
+clean:
+	rm -rf build/ dist/ *.egg-info src/*.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type d -name .pytest_cache -exec rm -rf {} +
+	find . -type d -name .ruff_cache -exec rm -rf {} +
+
+bench:
+	python scripts/benchmarks/benchmark_locomo.py --n-conversations 10 --top-k 10
+
+bench-quick:
+	python scripts/benchmarks/benchmark_locomo.py --n-conversations 3 --top-k 10
+
+tui:
+	pmb tui
+
+dashboard:
+	pmb dashboard

pmb_ai-0.1.0/NOTICE

@@ -0,0 +1,31 @@
+PMB - Personal Memory Brain
+Copyright 2026 PMB contributors
+
+This product includes software developed by the PMB contributors
+(https://github.com/yourname/pmb).
+
+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
+
+----------------------------------------------------------------------
+
+Third-party components and their licenses:
+
+- sentence-transformers (Apache-2.0)  - local embedding models
+- LanceDB (Apache-2.0)                - local vector store
+- FastMCP (Apache-2.0)                - MCP server framework
+- rank-bm25 (Apache-2.0)              - BM25 lexical retrieval
+- Typer / Rich (MIT)                  - CLI rendering
+- Textual (MIT)                       - TUI workspace
+- NumPy (BSD-3-Clause)                - numerical routines
+- PyYAML (MIT)                        - config loading
+
+Optional dependencies pulled in by `pmb[all]`:
+- anthropic (MIT)                     - consolidation backend
+- fastembed (Apache-2.0)              - ONNX embeddings
+
+Full license texts for these dependencies ship inside the installed
+distributions (look under site-packages/<pkg>-*.dist-info/licenses/).