helix-memory 4.0.1__tar.gz

helix_memory-4.0.1/.github/actions/setup-python-env/action.yml

@@ -0,0 +1,34 @@
+name: 'Setup Python Environment'
+description: 'Install Python, uv, and project dependencies'
+
+inputs:
+  python-version:
+    description: 'Python version to set up'
+    required: true
+  uv-version:
+    description: 'uv version to install'
+    required: false
+    default: '0.9.11'
+  install-dependencies:
+    description: 'Whether to run uv sync after setup'
+    required: false
+    default: 'true'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python ${{ inputs.python-version }}
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        version: ${{ inputs.uv-version }}
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install dependencies
+      if: inputs.install-dependencies == 'true'
+      shell: bash
+      run: uv sync --all-groups --frozen

helix_memory-4.0.1/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'

helix_memory-4.0.1/.github/workflows/ci.yml

@@ -0,0 +1,183 @@
+name: CI
+
+on:
+  push:
+    branches: ['main']
+  pull_request:
+    branches: ['main']
+
+permissions:
+  id-token: write
+  contents: write
+  pull-requests: write
+  actions: write
+
+jobs:
+  lint:
+    name: Lint (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run lint and format checks
+        run: uv run poe format
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run unit tests
+        env:
+          SECRET_KEY: ${{ secrets.SECRET_KEY }}
+        run: uv run poe test
+
+  update-hooks:
+    name: Update pre-commit hooks
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+          ref: ${{ github.head_ref }}
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: '3.13'
+
+      - name: Autoupdate pre-commit hooks
+        run: uv run pre-commit autoupdate
+
+      - name: Commit updated hooks
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add .pre-commit-config.yaml
+          git diff --staged --quiet || git commit -m "chore(config): update pre-commit hooks"
+          git push origin "HEAD:${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}"
+
+  breaking-changes:
+    name: Detect breaking changes
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    needs: [lint, test]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+          ref: main
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: '3.13'
+
+      - name: Get proposed version
+        id: proposed
+        run: |
+          VERSION=$(pipx run --spec python-semantic-release semantic-release --noop version --print)
+          echo "proposed=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Run pycracks
+        id: pycracks
+        continue-on-error: true
+        env:
+          SECRET_KEY: ${{ secrets.SECRET_KEY }}
+        run: |
+          pipx run pycracks \
+            --path "tests" \
+            --target-version "${{ steps.proposed.outputs.proposed }}" \
+            --test-command "uv run poe test"
+
+      - name: Create breaking change commit
+        if: steps.pycracks.outcome == 'failure'
+        run: |
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+          git commit --allow-empty \
+            -m "feat!: breaking change detected [skip ci]"
+          git push origin main
+
+  versioning:
+    name: Versioning
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    needs: [breaking-changes]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+          ref: main
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: '3.13'
+
+      - name: Bump version and update changelog
+        id: release
+        uses: python-semantic-release/python-semantic-release@v9.21.1
+        with:
+          github_token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+      version: ${{ steps.release.outputs.version }}
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && needs.versioning.outputs.released == 'true'
+    needs: [versioning]
+    environment:
+      name: pypi
+      url: https://pypi.org/p/helix-memory
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+          ref: main
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: '3.13'
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

helix_memory-4.0.1/.github/workflows/snyk.yml

@@ -0,0 +1,31 @@
+name: Snyk Security with uv
+
+on:
+  push:
+    branches: ['main']
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * 0' # 00:00 every Sunday
+
+jobs:
+  snyk_scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: '3.13'
+
+      - name: Export dependencies
+        run: uv export --format requirements-txt --output-file requirements.txt
+
+      - name: Run Snyk Open Source
+        uses: snyk/actions/python@master
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+        with:
+          command: test

helix_memory-4.0.1/.gitignore

@@ -0,0 +1,62 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+*.so
+
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+
+.venv/
+venv/
+ENV/
+env/
+
+pip-log.txt
+pip-delete-this-directory.txt
+
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+.mypy_cache/
+dmypy.json
+dmypy.txt
+.ruff_cache/
+
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+.DS_Store
+Thumbs.db
+
+site/
+
+.env
+.env.*

helix_memory-4.0.1/.pre-commit-config.yaml

@@ -0,0 +1,49 @@
+repos:
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.25
+    hooks:
+      - id: validate-pyproject
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: detect-private-key
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 'v0.15.13'
+    hooks:
+      - id: ruff-check
+        name: ruff
+        args: ['--fix']
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.9.4
+    hooks:
+      - id: bandit
+        args: ['-r', '-lll']
+
+  - repo: https://github.com/pylint-dev/pylint
+    rev: v4.0.5
+    hooks:
+      - id: pylint
+        types: [python]
+        additional_dependencies:
+          - loguru==0.7.3
+          - pydantic==2.13.4
+          - pytest==9.0.3
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.1.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - loguru==0.7.3
+          - pydantic==2.13.4
+          - pytest==9.0.3

helix_memory-4.0.1/CHANGELOG.md

@@ -0,0 +1,136 @@
+# CHANGELOG
+
+
+## v4.0.1 (2026-05-19)
+
+### Bug Fixes
+
+- **docs**: Update quickstart docs
+  ([`f16da2b`](https://github.com/justmatias/helix/commit/f16da2b8a34d732e6da7c5d13a4f6dce44bec57b))
+
+### Chores
+
+- Update project name to 'helix-memory', version to 4.0.0, and a…
+  ([#3](https://github.com/justmatias/helix/pull/3),
+  [`a680c86`](https://github.com/justmatias/helix/commit/a680c86e5e83c695979f1d775cde18ebed73fa74))
+
+* chore: update project name to 'helix-memory', version to 4.0.0, and adjust Python requirement to
+  >=3.13; enhance installation instructions in README and CI workflow for PyPI publishing
+
+* fix: add Snyk security scanning workflow for automated dependency checks
+
+* chore: update Python requirement to >=3.13 and rename package to 'helix-memory' with version 4.0.0
+
+* chore: update package version to reflect renaming to 'helix-memory'
+
+
+## v4.0.0 (2026-05-19)
+
+### Features
+
+- Breaking change detected [skip ci]
+  ([`ef40cce`](https://github.com/justmatias/helix/commit/ef40ccedbcb594d8bfa75fdc2b984e141cf84b1e))
+
+- Enhance Helix CLI with installation and uninstallation commands…
+  ([#2](https://github.com/justmatias/helix/pull/2),
+  [`172ebf0`](https://github.com/justmatias/helix/commit/172ebf0ae3eb96e845cd005051fda93bed249e02))
+
+* feat: enhance Helix CLI with installation and uninstallation commands for agent integration
+
+* chore(config): update pre-commit hooks
+
+* fix: refactor installer operations and reorganize modules
+
+* chore: fix lint issues and refactor installer tests
+
+* fix: extract prompt selection logic into separate functions for improved readability and
+  reusability
+
+* chore: remove comment
+
+---------
+
+Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
+
+
+## v3.0.0 (2026-05-14)
+
+### Chores
+
+- Restructure CLI application and enhance convention management
+  ([`78320e1`](https://github.com/justmatias/helix/commit/78320e1dd4ecf95bdc5c37b057ad8ac135ce2a92))
+
+- Update CLI structure and enhance command definitions with type annotations
+  ([`a2717a6`](https://github.com/justmatias/helix/commit/a2717a651c915192a647e7f5ed0dc51d6e8d950e))
+
+### Features
+
+- Breaking change detected [skip ci]
+  ([`52eddd9`](https://github.com/justmatias/helix/commit/52eddd91dc8e68981ecf6b6ff957fbf0a3ed9a29))
+
+
+## v2.0.0 (2026-05-14)
+
+### Bug Fixes
+
+- **ci**: Prevent semantic-release from re-triggering CI loop
+  ([`7aa43ea`](https://github.com/justmatias/helix/commit/7aa43ea6f8eb81652eb7d99ae1facdc8aadcde6d))
+
+Add [skip ci] to the release commit message so pushes from python-semantic-release do not trigger a
+  new workflow run.
+
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+
+### Features
+
+- Breaking change detected [skip ci]
+  ([`ed70a0d`](https://github.com/justmatias/helix/commit/ed70a0dc36f4e7b9d4ea43af2db93ede0e85b788))
+
+- Implement CLI for convention management with commands to remember, list, recall, and forget
+  conventions
+  ([`77fb37b`](https://github.com/justmatias/helix/commit/77fb37bd18bfa11163619c6a416d1ebd48b4fa6d))
+
+
+## v1.0.0 (2026-05-13)
+
+### Bug Fixes
+
+- Add convention class for managing conventions and enhance filtering functionality
+  ([`3517cb3`](https://github.com/justmatias/helix/commit/3517cb36376f537c87f8b55ec822a3a4ce1815b2))
+
+- Implement brain class for convention management and remove unused storage utilities
+  ([`f795485`](https://github.com/justmatias/helix/commit/f795485643854557076a73949b290c75e8b93bd3))
+
+- Update project configuration and enhance storage management functionality
+  ([`2cf4993`](https://github.com/justmatias/helix/commit/2cf4993dd94ebe4d6cc1882d0656d588ed609ccb))
+
+### Chores
+
+- Add initial project structure with configuration files, README, and core functionality
+  ([`fa05287`](https://github.com/justmatias/helix/commit/fa052873076828a4dd3c622ff5f9fba8a17b69a5))
+
+- Add pre-commit dependency and update lock file with new packages
+  ([`ce99c36`](https://github.com/justmatias/helix/commit/ce99c360602d23a5d701f1230f3ac077f3ca3c59))
+
+- Disable pylint invalid-name warning
+  ([`41c3c53`](https://github.com/justmatias/helix/commit/41c3c53049153d153b9dc7546fd6454f63cb88e3))
+
+- Fix lint issues
+  ([`1e94e90`](https://github.com/justmatias/helix/commit/1e94e90fa09d640f7501382e1e55658c04791c3b))
+
+- Streamline _filter_index_lines_by_tags method for improved readability
+  ([`9eb6dcc`](https://github.com/justmatias/helix/commit/9eb6dccde68c18fb1dae5b9a609e86b6f9543f7c))
+
+- Update build system configuration to use hatchling and specify wheel target
+  ([`4e9fc37`](https://github.com/justmatias/helix/commit/4e9fc3713c0c41a60e1af22918129938bb4b0d99))
+
+- **docs**: Add implementation plan
+  ([`b10b684`](https://github.com/justmatias/helix/commit/b10b684e9412c15db733fa3c6de65005c3107846))
+
+- **release**: Release version 1.0.0
+  ([`bc81d7f`](https://github.com/justmatias/helix/commit/bc81d7fa301c66ff1607542928fc38b75da265e7))
+
+### Features
+
+- Breaking change detected [skip ci]
+  ([`1229f2e`](https://github.com/justmatias/helix/commit/1229f2efc35bec295ea609ea18d61de573f33ede))

helix_memory-4.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matías Giménez
+
+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.

helix_memory-4.0.1/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: helix-memory
+Version: 4.0.1
+Summary: A lightweight, multi-client memory layer that persists cross-project coding conventions
+Author-email: Matias Gimenez <matiasgimenez.dev@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic-settings>=2.14.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: typer>=0.25.1
+Description-Content-Type: text/markdown
+
+# Helix
+
+Global convention memory for AI coding agents — persist your coding preferences once, surface them in every Claude Code, Cursor, or MCP-compatible session.
+
+## Install
+
+```bash
+# With uv (recommended)
+uv tool install helix-memory
+
+# Or with pip
+pip install helix-memory
+```
+
+## Quick start
+
+```bash
+# 1. Hook Helix into your agent (Claude Code, Cursor, …).
+helix install
+
+# 2. Save your first convention.
+helix remember pydantic-validation \
+  "Prefer Pydantic v2 for any external-boundary validation." \
+  --tags python,validation
+```
+
+From there, your next agent session will see the conventions automatically.
+
+## CLI
+
+```bash
+helix remember <name> "<body>" --tags <comma,separated>
+helix list [--tags <tag>]
+helix recall "<query>" [--tags <tag>]
+helix forget <name>
+helix install   # wire Helix into your agent
+helix uninstall # remove the integration
+helix serve     # start the MCP server
+```
+
+## MCP server
+
+`helix serve` exposes four tools to any MCP-compatible client: `remember`, `recall`, `list_conventions`, `forget`.
+
+Add to your client's MCP config (e.g. `~/.claude/claude_desktop_config.json`):
+
+```json
+{
+	"mcpServers": {
+		"helix": {
+			"command": "helix",
+			"args": ["serve"]
+		}
+	}
+}
+```
+
+## License
+
+MIT

helix_memory-4.0.1/README.md

@@ -0,0 +1,60 @@
+# Helix
+
+Global convention memory for AI coding agents — persist your coding preferences once, surface them in every Claude Code, Cursor, or MCP-compatible session.
+
+## Install
+
+```bash
+# With uv (recommended)
+uv tool install helix-memory
+
+# Or with pip
+pip install helix-memory
+```
+
+## Quick start
+
+```bash
+# 1. Hook Helix into your agent (Claude Code, Cursor, …).
+helix install
+
+# 2. Save your first convention.
+helix remember pydantic-validation \
+  "Prefer Pydantic v2 for any external-boundary validation." \
+  --tags python,validation
+```
+
+From there, your next agent session will see the conventions automatically.
+
+## CLI
+
+```bash
+helix remember <name> "<body>" --tags <comma,separated>
+helix list [--tags <tag>]
+helix recall "<query>" [--tags <tag>]
+helix forget <name>
+helix install   # wire Helix into your agent
+helix uninstall # remove the integration
+helix serve     # start the MCP server
+```
+
+## MCP server
+
+`helix serve` exposes four tools to any MCP-compatible client: `remember`, `recall`, `list_conventions`, `forget`.
+
+Add to your client's MCP config (e.g. `~/.claude/claude_desktop_config.json`):
+
+```json
+{
+	"mcpServers": {
+		"helix": {
+			"command": "helix",
+			"args": ["serve"]
+		}
+	}
+}
+```
+
+## License
+
+MIT