memorymesh 2.0.0__tar.gz

memorymesh-2.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,47 @@
+---
+name: Bug Report
+about: Report a bug to help us improve MemoryMesh
+title: "[Bug] "
+labels: bug
+assignees: ''
+---
+
+## Description
+
+A clear and concise description of the bug.
+
+## Steps to Reproduce
+
+1. Install MemoryMesh with `pip install memorymesh`
+2. Run the following code:
+
+```python
+from memorymesh import MemoryMesh
+# Minimal code to reproduce the issue
+```
+
+3. Observe the error.
+
+## Expected Behavior
+
+A clear description of what you expected to happen.
+
+## Actual Behavior
+
+A clear description of what actually happened. Include any error messages or tracebacks.
+
+```
+Paste error output here
+```
+
+## Environment
+
+- **OS:** (e.g., Ubuntu 22.04, macOS 14, Windows 11)
+- **Python version:** (e.g., 3.12.1)
+- **MemoryMesh version:** (e.g., 0.1.0)
+- **Embedding provider:** (e.g., none, local, ollama, openai)
+- **Installation method:** (e.g., `pip install memorymesh`, `pip install memorymesh[local]`)
+
+## Additional Context
+
+Add any other context about the problem here (screenshots, related issues, etc.).

memorymesh-2.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,35 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement for MemoryMesh
+title: "[Feature] "
+labels: enhancement
+assignees: ''
+---
+
+## Description
+
+A clear and concise description of the feature you would like to see.
+
+## Use Case
+
+Describe the problem or workflow this feature would address. Why is this feature important to you?
+
+```python
+# If applicable, show how you imagine using this feature:
+from memorymesh import MemoryMesh
+
+memory = MemoryMesh()
+# Example usage of the proposed feature
+```
+
+## Proposed Solution
+
+Describe how you think this feature should work. Include API design ideas if you have them.
+
+## Alternatives Considered
+
+Describe any alternative solutions or workarounds you have considered.
+
+## Additional Context
+
+Add any other context, references, or screenshots about the feature request here.

memorymesh-2.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+## Description
+
+Describe the changes in this pull request. What problem does it solve? Link any related issues.
+
+Closes #(issue number)
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+- [ ] CI/Build configuration change
+
+## How Has This Been Tested?
+
+Describe the tests you ran to verify your changes. Provide instructions so reviewers can reproduce.
+
+```bash
+make test
+```
+
+## Checklist
+
+- [ ] My code follows the project code style
+- [ ] I have added type hints to all public functions and methods
+- [ ] I have added docstrings to all public classes, methods, and functions
+- [ ] I have added tests that prove my fix or feature works
+- [ ] All new and existing tests pass (`make test`)
+- [ ] The linter passes (`make lint`)
+- [ ] The type checker passes (`make typecheck`)
+- [ ] I have updated documentation if needed
+- [ ] My changes do not introduce new warnings

memorymesh-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run ruff linter
+        run: ruff check src/ tests/
+
+      - name: Run ruff formatter check
+        run: ruff format --check src/ tests/
+
+      - name: Run mypy
+        run: mypy src/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short

memorymesh-2.0.0/.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install mkdocs-material>=9.0
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

memorymesh-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,67 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch'
+    environment: testpypi
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    environment: pypi
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

memorymesh-2.0.0/.gitignore

@@ -0,0 +1,76 @@
+# Python byte-compiled / optimized files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+eggs/
+wheels/
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Linting
+.ruff_cache/
+
+# IDEs and editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.settings/
+
+# OS files
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# SQLite databases (user data, not committed)
+*.db
+*.sqlite
+*.sqlite3
+
+# MemoryMesh project-local data directory
+.memorymesh/
+
+# Node (in case of any JS tooling)
+node_modules/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# MkDocs site output
+site/
+
+# Build artifacts
+*.so
+*.dylib
+*.dll

memorymesh-2.0.0/CLAUDE.md

@@ -0,0 +1,122 @@
+# CLAUDE.md - Guidance for Claude Code
+
+## Repository Purpose
+
+MemoryMesh is an open-source, embeddable AI memory library. It provides persistent, intelligent memory for any LLM application using SQLite as the storage backend. The design philosophy mirrors SQLite itself: simple, reliable, zero-dependency, and embeddable.
+
+## Key Entry Points
+
+- `src/memorymesh/core.py` -- The main `MemoryMesh` class. This is the primary public API and the starting point for understanding the codebase.
+- `src/memorymesh/store.py` -- SQLite storage layer. Handles all database operations, schema management, and memory persistence.
+- `src/memorymesh/embeddings.py` -- Pluggable embedding providers. Abstracts over local (sentence-transformers), Ollama, OpenAI, and keyword-based matching.
+- `src/memorymesh/relevance.py` -- Relevance scoring engine. Combines vector similarity, keyword overlap, and time-based decay to rank memories.
+- `src/memorymesh/mcp_server.py` -- MCP (Model Context Protocol) server. Exposes memory tools over stdin/stdout JSON-RPC for use with Claude Code, Cursor, and other MCP-compatible clients.
+- `src/memorymesh/memory.py` -- The `Memory` dataclass. Defines the core data model used throughout the library.
+
+## Architecture
+
+```
+core.py (public API: remember / recall / forget)
+  -> store.py (SQLite read/write, schema migrations)
+     - project store: <project-root>/.memorymesh/memories.db
+     - global store:  ~/.memorymesh/global.db
+  -> embeddings.py (pluggable: local, ollama, openai, none)
+  -> relevance.py (scoring: similarity + keywords + time decay)
+```
+
+MemoryMesh uses a **hybrid dual-store** pattern:
+
+- **Project store** (`<project-root>/.memorymesh/memories.db`) -- project-specific memories, decisions, and patterns. Isolated per project.
+- **Global store** (`~/.memorymesh/global.db`) -- user preferences, identity, and cross-project facts. Shared across all projects.
+
+`recall()` queries both stores by default and merges results. `forget_all()` defaults to clearing only the project store (global is protected). The `scope` parameter (`"project"` or `"global"`) controls routing throughout the API.
+
+No external services are required for the base installation.
+
+## Development
+
+### Testing
+```bash
+make test          # Run full test suite with pytest
+pytest tests/      # Run tests directly
+pytest tests/ -x   # Stop on first failure
+```
+
+### Building
+```bash
+make build         # Build distribution packages
+```
+
+### Linting and Formatting
+```bash
+make lint          # Run ruff linter
+make format        # Auto-format with ruff
+make typecheck     # Run mypy type checking
+```
+
+### Full Check
+```bash
+make all           # Run lint + test + typecheck
+```
+
+## Design Principles
+
+1. **Simplicity** -- The public API should be obvious. `remember()`, `recall()`, `forget()`. Minimize cognitive overhead.
+2. **Zero External Dependencies** -- The base install has no dependencies beyond the Python standard library. All third-party packages (sentence-transformers, openai, httpx) are optional extras.
+3. **Framework-Agnostic** -- MemoryMesh must never depend on or assume any specific LLM framework (LangChain, LlamaIndex, etc.). It is a library, not a framework.
+4. **Cross-Platform** -- Must work on Linux, macOS, and Windows without platform-specific code paths where possible.
+5. **Privacy-First** -- No telemetry, no phone-home, no cloud calls unless the user explicitly configures an external embedding provider.
+
+## Memory (MemoryMesh)
+
+MemoryMesh is configured as an MCP tool in this project. You MUST use it proactively -- it is the project's own product and dogfooding it is essential.
+
+### When to `recall`
+
+- **Start of every conversation**: Call `recall` with a summary of the user's request to check for relevant prior context, decisions, patterns, or past mistakes.
+- **Before making architectural decisions**: Recall to check if this was decided before.
+- **When debugging**: Recall to check if this problem or error was encountered previously.
+- **When unsure about conventions**: Recall to check if there's a stored preference or pattern.
+
+### When to `remember`
+
+- **After completing a task**: Store key decisions, patterns discovered, and architectural choices made.
+- **When the user teaches you something**: Immediately remember it (scope: global for preferences, project for project-specific facts).
+- **After fixing a non-trivial bug**: Remember the root cause and fix so it's not repeated.
+- **When discovering undocumented patterns**: Store conventions found in the codebase.
+- **After a multi-step investigation**: Remember the conclusion so future sessions don't repeat the work.
+
+### What to remember
+
+- Architectural decisions and their rationale
+- Bug fixes, root causes, and solutions that took multiple attempts
+- User preferences confirmed during work
+- File patterns and conventions discovered
+- Implementation approaches that worked (or didn't)
+- Test strategies and edge cases found
+
+### What NOT to remember
+
+- Trivial single-use facts (e.g., "ran tests, they passed")
+- Information already written in this CLAUDE.md file
+- Temporary state or in-progress work details
+- Verbatim code snippets (store the insight, not the code)
+
+### Scope guidance
+
+- Use `scope: "project"` for project-specific decisions, architecture, and patterns.
+- Use `scope: "global"` for user preferences, identity, and cross-project facts.
+
+### Priority
+
+- **Prefer MemoryMesh over auto-memory files** for persistent knowledge storage. MemoryMesh is the product we are building -- using it validates the product and builds a useful knowledge base.
+
+## Code Conventions
+
+- **Type hints** are required on all public functions and methods.
+- **Docstrings** are required on all public classes, methods, and functions. Use Google-style docstrings.
+- **Dataclasses** are preferred over plain dicts for structured data.
+- **No global mutable state.** All state lives in class instances.
+- **License:** MIT. All source files should be compatible with this license.
+- **Formatting:** Enforced by ruff. Run `make format` before committing.
+- **Testing:** All new features and bug fixes must include tests. Use pytest.

memorymesh-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,163 @@
+# Contributing to MemoryMesh
+
+Thank you for your interest in contributing to MemoryMesh. This is an open project built to serve humanity by making AI memory accessible, free, and simple. Every contribution -- whether it is a bug fix, a feature, documentation, or a thoughtful issue report -- helps move that mission forward.
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.9 or later
+- Git
+
+### Setting Up the Development Environment
+
+1. **Fork and clone the repository:**
+
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/memorymesh.git
+   cd memorymesh
+   ```
+
+2. **Create a virtual environment:**
+
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+3. **Install in development mode with all dependencies:**
+
+   ```bash
+   pip install -e ".[dev,all]"
+   ```
+
+   Or use the Makefile shortcut:
+
+   ```bash
+   make install
+   ```
+
+4. **Verify everything works:**
+
+   ```bash
+   make all   # Runs lint + tests + type checking
+   ```
+
+---
+
+## Code Style
+
+We use **ruff** for both linting and formatting. The configuration is in `pyproject.toml`.
+
+### Requirements
+
+- **Type hints** are required on all public functions and methods.
+- **Docstrings** are required on all public classes, methods, and functions. Use Google-style docstrings.
+- **No wildcard imports.** Always import specific names.
+- **Prefer dataclasses** over plain dictionaries for structured data.
+
+### Running the Linter and Formatter
+
+```bash
+make lint      # Check for issues
+make format    # Auto-fix formatting
+make typecheck # Run mypy
+```
+
+Please ensure `make lint` and `make typecheck` pass before submitting a pull request.
+
+---
+
+## Testing
+
+We use **pytest** for all testing.
+
+```bash
+make test              # Run the full test suite
+pytest tests/ -x       # Stop on first failure
+pytest tests/ -v       # Verbose output
+pytest tests/ -k name  # Run tests matching a pattern
+```
+
+### Testing Guidelines
+
+- All new features must include tests.
+- All bug fixes must include a regression test.
+- Tests should be fast. Avoid network calls in unit tests; mock external services.
+- Place tests in the `tests/` directory, mirroring the source structure.
+
+---
+
+## Pull Request Process
+
+1. **Fork** the repository and create a new branch from `main`:
+
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes.** Keep commits focused and atomic.
+
+3. **Run the full check suite:**
+
+   ```bash
+   make all
+   ```
+
+4. **Push your branch** and open a pull request against `main`.
+
+5. **Fill out the PR template.** Describe what changed, why, and how to test it.
+
+6. **Respond to review feedback.** We aim to review all PRs within a few days.
+
+### PR Checklist
+
+- [ ] Code follows the project style guidelines
+- [ ] Type hints are included for all public APIs
+- [ ] Docstrings are included for all public APIs
+- [ ] Tests are added or updated
+- [ ] `make lint` passes
+- [ ] `make typecheck` passes
+- [ ] `make test` passes
+- [ ] Documentation is updated if needed
+
+---
+
+## Reporting Issues
+
+We use GitHub Issues for tracking bugs and feature requests.
+
+### Bug Reports
+
+Use the **Bug Report** issue template. Include:
+
+- A clear description of the problem
+- Steps to reproduce
+- Expected vs. actual behavior
+- Your environment (OS, Python version, MemoryMesh version, embedding provider)
+
+### Feature Requests
+
+Use the **Feature Request** issue template. Include:
+
+- A description of the feature
+- The use case it addresses
+- A proposed solution (if you have one)
+
+---
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). By participating, you agree to uphold a welcoming, inclusive, and respectful environment for everyone.
+
+We have zero tolerance for harassment, discrimination, or disrespectful behavior. If you experience or witness unacceptable behavior, please report it by opening an issue or contacting the maintainers directly.
+
+---
+
+## Questions?
+
+If you have questions about contributing, feel free to open a discussion on GitHub or reach out by filing an issue. We are happy to help you get started.
+
+Thank you for helping build the future of open AI memory.