boring-agent-memory 0.2.2__tar.gz

boring_agent_memory-0.2.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Report a reproducible problem
+title: "[Bug]: "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+Describe the bug.
+
+## Reproduction
+
+```bash
+# commands
+```
+
+## Expected Behavior
+
+What should have happened?
+
+## Actual Behavior
+
+What happened instead?
+
+## Environment
+
+- OS:
+- Python version:
+- Boring Agent Memory version or commit:
+
+## Sanitized Config Or Fixture
+
+Paste only sanitized examples. Do not include secrets, `.env` files, raw inboxes, browser profiles, auth files, or private transcripts.

boring_agent_memory-0.2.2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

boring_agent_memory-0.2.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Propose an improvement
+title: "[Feature]: "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What user problem does this solve?
+
+## Proposed Solution
+
+Describe the smallest useful implementation.
+
+## Alternatives Considered
+
+What else did you consider?
+
+## Canonical-First Fit
+
+Explain how this preserves source-grounded retrieval and avoids treating memory as truth.

boring_agent_memory-0.2.2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Summary
+
+Describe the change.
+
+## Validation
+
+```bash
+python -m unittest discover -s tests
+```
+
+## Checklist
+
+- [ ] Tests cover the changed behavior.
+- [ ] Docs are updated for user-visible changes.
+- [ ] No generated databases, caches, local secrets, or private files are included.
+- [ ] The change preserves canonical-first retrieval semantics.

boring_agent_memory-0.2.2/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: publish
+
+permissions:
+  contents: read
+
+on:
+  release:
+    types: [published]
+
+# Building runs third-party build tools, so it gets no publishing credential;
+# only the upload job can request the PyPI OIDC token. Actions are pinned by SHA.
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.14"
+      - name: Check the tag matches the package version
+        run: test "$GITHUB_REF_NAME" = "v$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+      - name: Build package
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

boring_agent_memory-0.2.2/.github/workflows/tests.yml

@@ -0,0 +1,35 @@
+name: tests
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - name: Install package
+        run: python -m pip install -e . build
+      - name: Run tests
+        run: python -m unittest discover -s tests
+      - name: Run memory eval
+        run: >
+          bam eval --json
+          --min-recall-at-1 1.0
+          --min-recall-at-3 1.0
+          --min-source-accuracy 1.0
+          --min-snippet-term-rate 1.0
+          --min-stale-detection-rate 1.0
+          --max-privacy-leaks 0
+      - name: Build package
+        run: python -m build

boring_agent_memory-0.2.2/CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+# Code of Conduct
+
+This project follows the Contributor Covenant Code of Conduct, version 2.1.
+
+## Our Pledge
+
+We pledge to make 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, caste, color, 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
+- giving and gracefully accepting constructive feedback
+- focusing on what is best for the community
+- showing empathy toward other community members
+
+Examples of unacceptable behavior:
+
+- sexualized language or imagery
+- insulting or derogatory comments
+- public or private harassment
+- publishing others' private information without permission
+- other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior. Maintainers may remove, edit, or reject comments, commits, issues, and pull requests that are not aligned with this Code of Conduct.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers once a public contact path is available.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1.

boring_agent_memory-0.2.2/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+Thanks for considering a contribution to Boring Agent Memory.
+
+This project values small, auditable changes that preserve the canonical-first memory model.
+
+## Development Setup
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e .
+```
+
+## Test
+
+```bash
+python -m unittest discover -s tests
+python -m pip install 'mypy>=1.14,<3' 'ruff>=0.9,<1'
+ruff check src tests scripts
+mypy src/boring_agent_memory
+```
+
+CI runs the tests, the eval gates, and a package build on Python 3.14.
+[docs/release-checklist.md](docs/release-checklist.md) lists the longer checks to run before a release.
+
+## Design Rules
+
+- Keep memory retrieval local-first by default.
+- Do not add hosted services or network calls to core retrieval.
+- Do not auto-ingest raw conversations, raw tool output, inboxes, browser profiles, or secrets.
+- Return source paths and snippets rather than unsupported conclusions.
+- Keep the agent-facing tool surface small.
+- Treat canonical files as truth and the index as rebuildable recall.
+
+## Pull Request Checklist
+
+- Tests cover the changed behavior.
+- Docs are updated for user-visible changes.
+- New config fields are documented in `docs/configuration.md`.
+- New CLI behavior is documented in `docs/cli.md`.
+- Generated files, databases, caches, and local secrets are not included.
+
+## AI Assistance
+
+AI tools are welcome.
+Say in the pull request that you used one, run the change yourself, and be ready to explain every line.
+
+## Reporting Bugs
+
+Include:
+
+- operating system
+- Python version
+- command used
+- expected result
+- actual result
+- minimal sanitized config or fixture
+
+Do not include secrets, raw inboxes, private transcripts, browser profiles, or `.env` files.

boring_agent_memory-0.2.2/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Boring Agent Memory 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.
+

boring_agent_memory-0.2.2/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md
+include LICENSE
+include CONTRIBUTING.md
+include SECURITY.md
+include CODE_OF_CONDUCT.md
+recursive-include docs *.md
+recursive-include examples *.md *.yaml
+recursive-include evals *.md *.jsonl
+recursive-include benchmarks *.md *.json *.jsonl
+recursive-include proposals *.md
+recursive-include scripts *.py
+recursive-include tests *.py
+recursive-include .github *.md *.yml

boring_agent_memory-0.2.2/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: boring-agent-memory
+Version: 0.2.2
+Summary: A boring, local-first BM25 memory layer for AI agents.
+Author: Boring Agent Memory contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hskl18/boring-agent-memory
+Project-URL: Repository, https://github.com/hskl18/boring-agent-memory
+Project-URL: Issues, https://github.com/hskl18/boring-agent-memory/issues
+Keywords: agent-memory,bm25,sqlite,fts5,rag,local-first,retrieval,source-grounded,privacy-preserving
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.15
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: embeddings
+Requires-Dist: fastembed<0.9,>=0.8.0; extra == "embeddings"
+Dynamic: license-file
+
+# Boring Agent Memory
+
+[![tests](https://github.com/hskl18/boring-agent-memory/actions/workflows/tests.yml/badge.svg)](https://github.com/hskl18/boring-agent-memory/actions/workflows/tests.yml)
+
+Local BM25 recall over the files your agent already trusts, with line citations and a check that each source still matches what was indexed.
+
+**Status: alpha.** The CLI, Python API, and index schema may still change before 1.0.
+
+Most agent memory failures are not failures of semantic search.
+They are failures of trust: stale state, missing provenance, private data captured by default, and memory overriding the source of truth.
+
+Boring Agent Memory indexes the docs, skills, runbooks, bug logs, and ADRs you choose with SQLite FTS5.
+It returns source paths and snippets, and your agent reads the cited file before it acts.
+It needs no hosted service, embedding API, vector database, model download, or account.
+
+## Install
+
+```bash
+python -m pip install boring-agent-memory
+```
+
+It needs Python 3.11 or newer.
+
+## Try It
+
+```bash
+mkdir notes
+printf '# Deploys\n\nRoll back database migrations within 15 minutes.\n' > notes/deploys.md
+
+bam build --include notes
+bam query "roll back migrations"
+```
+
+```text
+deploys.md  score=-3e-06
+  /path/to/notes/deploys.md
+  # Deploys
+
+[Roll] [back] database [migrations] within 15 minutes.
+```
+
+Now change the file and check whether the index still matches it:
+
+```bash
+printf '# Deploys\n\nRoll back within 30 minutes.\n' > notes/deploys.md
+
+bam inspect notes/deploys.md
+bam update --include notes
+```
+
+`bam inspect` reports `content_hash_match: False` until `bam update` picks up the edit.
+
+## Use Your Own Files
+
+Point a config at the files you trust and save it as `memory.yaml`:
+
+```yaml
+index_path: ~/.bam/memory.db
+source_type: canonical_file
+workspace: ~/project/app
+
+include:
+  - ~/agent/skills
+  - ~/project/*/docs
+
+exclude:
+  - "**/secrets/**"
+```
+
+```bash
+bam build --config memory.yaml --json
+bam update --config memory.yaml --dry-run --json
+bam update --config memory.yaml --json
+
+bam --db ~/.bam/memory.db query "rollback policy" --limit 5 --json
+```
+
+A database that does not exist is an error, so a mistyped path cannot look like an empty memory.
+
+## Use It From An Agent
+
+```python
+from boring_agent_memory import memory_query
+
+results = memory_query(
+    "rollback policy for database migrations",
+    limit=5,
+    source_type="canonical_file",
+    db_path="~/.bam/memory.db",
+)
+
+for result in results:
+    print(result.citation)
+    print(result.snippet)
+```
+
+Other processes can use `bam serve --stdio`, which speaks JSON lines. See the [CLI reference](https://github.com/hskl18/boring-agent-memory/blob/main/docs/cli.md).
+
+Agent instructions to copy are in [docs/agent-prompt.md](https://github.com/hskl18/boring-agent-memory/blob/main/docs/agent-prompt.md), with setups for [Claude Code](https://github.com/hskl18/boring-agent-memory/blob/main/examples/claude_code.md), [Codex](https://github.com/hskl18/boring-agent-memory/blob/main/examples/codex.md), and [Hermes](https://github.com/hskl18/boring-agent-memory/blob/main/docs/hermes-integration.md).
+
+## Evidence
+
+On Benchmark v2's 12 synthetic queries, chunked BM25 finds the right lines first every time, while whole-document BM25 finds the right file 91% of the time and never the right lines.
+These are deterministic fixture results, not production traffic or a broad semantic-memory claim.
+See [Benchmark v2](https://github.com/hskl18/boring-agent-memory/blob/main/docs/benchmark-v2.md) and [why BM25 comes first](https://github.com/hskl18/boring-agent-memory/blob/main/docs/canonical-first-memory.md#why-bm25-first).
+
+## What It Is Not
+
+- Not a chatbot brain or an auto-capture memory system. It indexes only paths you name.
+- Not a replacement for semantic search over vague queries.
+- Not an authority over current files. Canonical files come first, BM25 recall second, model memory last.
+- Not a hosted service or a vector database.
+
+## Privacy
+
+Secret-bearing paths are skipped and common secret patterns are redacted before indexing, but these are guardrails, not a formal secret scanner.
+Read the [privacy model](https://github.com/hskl18/boring-agent-memory/blob/main/docs/privacy-model.md) before choosing what to index.
+
+## Documentation
+
+- [CLI reference](https://github.com/hskl18/boring-agent-memory/blob/main/docs/cli.md)
+- [Configuration](https://github.com/hskl18/boring-agent-memory/blob/main/docs/configuration.md)
+- [Python API](https://github.com/hskl18/boring-agent-memory/blob/main/docs/python-api.md)
+- [Architecture](https://github.com/hskl18/boring-agent-memory/blob/main/docs/architecture.md)
+- [Comparison with other memory tools](https://github.com/hskl18/boring-agent-memory/blob/main/docs/comparison.md)
+- [Status and known limits](https://github.com/hskl18/boring-agent-memory/blob/main/docs/status-and-gaps.md)
+- [Roadmap](https://github.com/hskl18/boring-agent-memory/blob/main/docs/roadmap.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/hskl18/boring-agent-memory/blob/main/CONTRIBUTING.md), and read [SECURITY.md](https://github.com/hskl18/boring-agent-memory/blob/main/SECURITY.md) before sharing logs, configs, or memory fixtures.
+
+## License
+
+MIT

boring_agent_memory-0.2.2/README.md

@@ -0,0 +1,135 @@
+# Boring Agent Memory
+
+[![tests](https://github.com/hskl18/boring-agent-memory/actions/workflows/tests.yml/badge.svg)](https://github.com/hskl18/boring-agent-memory/actions/workflows/tests.yml)
+
+Local BM25 recall over the files your agent already trusts, with line citations and a check that each source still matches what was indexed.
+
+**Status: alpha.** The CLI, Python API, and index schema may still change before 1.0.
+
+Most agent memory failures are not failures of semantic search.
+They are failures of trust: stale state, missing provenance, private data captured by default, and memory overriding the source of truth.
+
+Boring Agent Memory indexes the docs, skills, runbooks, bug logs, and ADRs you choose with SQLite FTS5.
+It returns source paths and snippets, and your agent reads the cited file before it acts.
+It needs no hosted service, embedding API, vector database, model download, or account.
+
+## Install
+
+```bash
+python -m pip install boring-agent-memory
+```
+
+It needs Python 3.11 or newer.
+
+## Try It
+
+```bash
+mkdir notes
+printf '# Deploys\n\nRoll back database migrations within 15 minutes.\n' > notes/deploys.md
+
+bam build --include notes
+bam query "roll back migrations"
+```
+
+```text
+deploys.md  score=-3e-06
+  /path/to/notes/deploys.md
+  # Deploys
+
+[Roll] [back] database [migrations] within 15 minutes.
+```
+
+Now change the file and check whether the index still matches it:
+
+```bash
+printf '# Deploys\n\nRoll back within 30 minutes.\n' > notes/deploys.md
+
+bam inspect notes/deploys.md
+bam update --include notes
+```
+
+`bam inspect` reports `content_hash_match: False` until `bam update` picks up the edit.
+
+## Use Your Own Files
+
+Point a config at the files you trust and save it as `memory.yaml`:
+
+```yaml
+index_path: ~/.bam/memory.db
+source_type: canonical_file
+workspace: ~/project/app
+
+include:
+  - ~/agent/skills
+  - ~/project/*/docs
+
+exclude:
+  - "**/secrets/**"
+```
+
+```bash
+bam build --config memory.yaml --json
+bam update --config memory.yaml --dry-run --json
+bam update --config memory.yaml --json
+
+bam --db ~/.bam/memory.db query "rollback policy" --limit 5 --json
+```
+
+A database that does not exist is an error, so a mistyped path cannot look like an empty memory.
+
+## Use It From An Agent
+
+```python
+from boring_agent_memory import memory_query
+
+results = memory_query(
+    "rollback policy for database migrations",
+    limit=5,
+    source_type="canonical_file",
+    db_path="~/.bam/memory.db",
+)
+
+for result in results:
+    print(result.citation)
+    print(result.snippet)
+```
+
+Other processes can use `bam serve --stdio`, which speaks JSON lines. See the [CLI reference](https://github.com/hskl18/boring-agent-memory/blob/main/docs/cli.md).
+
+Agent instructions to copy are in [docs/agent-prompt.md](https://github.com/hskl18/boring-agent-memory/blob/main/docs/agent-prompt.md), with setups for [Claude Code](https://github.com/hskl18/boring-agent-memory/blob/main/examples/claude_code.md), [Codex](https://github.com/hskl18/boring-agent-memory/blob/main/examples/codex.md), and [Hermes](https://github.com/hskl18/boring-agent-memory/blob/main/docs/hermes-integration.md).
+
+## Evidence
+
+On Benchmark v2's 12 synthetic queries, chunked BM25 finds the right lines first every time, while whole-document BM25 finds the right file 91% of the time and never the right lines.
+These are deterministic fixture results, not production traffic or a broad semantic-memory claim.
+See [Benchmark v2](https://github.com/hskl18/boring-agent-memory/blob/main/docs/benchmark-v2.md) and [why BM25 comes first](https://github.com/hskl18/boring-agent-memory/blob/main/docs/canonical-first-memory.md#why-bm25-first).
+
+## What It Is Not
+
+- Not a chatbot brain or an auto-capture memory system. It indexes only paths you name.
+- Not a replacement for semantic search over vague queries.
+- Not an authority over current files. Canonical files come first, BM25 recall second, model memory last.
+- Not a hosted service or a vector database.
+
+## Privacy
+
+Secret-bearing paths are skipped and common secret patterns are redacted before indexing, but these are guardrails, not a formal secret scanner.
+Read the [privacy model](https://github.com/hskl18/boring-agent-memory/blob/main/docs/privacy-model.md) before choosing what to index.
+
+## Documentation
+
+- [CLI reference](https://github.com/hskl18/boring-agent-memory/blob/main/docs/cli.md)
+- [Configuration](https://github.com/hskl18/boring-agent-memory/blob/main/docs/configuration.md)
+- [Python API](https://github.com/hskl18/boring-agent-memory/blob/main/docs/python-api.md)
+- [Architecture](https://github.com/hskl18/boring-agent-memory/blob/main/docs/architecture.md)
+- [Comparison with other memory tools](https://github.com/hskl18/boring-agent-memory/blob/main/docs/comparison.md)
+- [Status and known limits](https://github.com/hskl18/boring-agent-memory/blob/main/docs/status-and-gaps.md)
+- [Roadmap](https://github.com/hskl18/boring-agent-memory/blob/main/docs/roadmap.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/hskl18/boring-agent-memory/blob/main/CONTRIBUTING.md), and read [SECURITY.md](https://github.com/hskl18/boring-agent-memory/blob/main/SECURITY.md) before sharing logs, configs, or memory fixtures.
+
+## License
+
+MIT

boring_agent_memory-0.2.2/SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy
+
+Boring Agent Memory is local-first, but it can still index sensitive text if configured incorrectly.
+
+## Supported Versions
+
+Security fixes target the latest release.
+
+## Reporting A Vulnerability
+
+Report suspected vulnerabilities privately through [GitHub private vulnerability reporting](https://github.com/hskl18/boring-agent-memory/security/advisories/new).
+Do not open a public issue containing secrets, credentials, or private content.
+
+## Sensitive Data Guidance
+
+Do not share:
+
+- `.env` files
+- API keys or tokens
+- private keys
+- raw browser profiles
+- raw email exports
+- raw terminal logs
+- unsanitized transcripts
+- local SQLite memory databases that may contain private content
+
+Use synthetic fixtures or sanitized snippets when reporting issues.
+
+## Security Model
+
+The project provides privacy guardrails:
+
+- explicit include paths
+- default secret-bearing path excludes
+- secret-pattern redaction
+- local SQLite storage
+- no hosted service dependency
+
+These guardrails are not a formal data-loss-prevention system.
+Users are responsible for selecting trusted include paths.