agent-memory-sdk 0.1.0__tar.gz

agent_memory_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,151 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4.2.2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5.5.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: |
+          python -m pytest tests/ -v --tb=short
+
+      - name: Run type checking
+        run: |
+          pip install mypy
+          mypy agent_memory/ --ignore-missing-imports || true
+
+      - name: Run linting
+        run: |
+          pip install ruff
+          ruff check agent_memory/ tests/
+
+  benchmark:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/'))
+
+    steps:
+      - uses: actions/checkout@v4.2.2
+
+      - name: Set up Python
+        uses: actions/setup-python@v5.5.0
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run benchmark
+        run: |
+          agent-memory benchmark --seed --repeat 3
+
+      - name: Run evaluation
+        run: |
+          agent-memory eval
+
+  docker:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4.2.2
+        with:
+          fetch-depth: 0  # Need full history for version detection
+
+      - name: Build Docker image
+        run: |
+          echo "GITHUB_REF_NAME=${GITHUB_REF_NAME}"
+          echo "GITHUB_REF=${GITHUB_REF}"
+          
+          # Generate a valid PEP 440 version
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            # For tags, use the tag name (strip 'v' prefix if present) - clean version for PyPI
+            VERSION=${GITHUB_REF_NAME#v}
+          elif [[ "${GITHUB_REF_NAME}" == "main" ]]; then
+            # For main branch, use a dev version with commit SHA (PEP 440 compliant)
+            VERSION="0.0.0.dev0+$(git rev-parse --short HEAD)"
+          else
+            # For other branches, use branch name sanitized + commit SHA (PEP 440 compliant)
+            BRANCH=$(echo "${GITHUB_REF_NAME}" | sed 's/[^a-zA-Z0-9]/-/g')
+            VERSION="0.0.0.dev0+${BRANCH}.$(git rev-parse --short HEAD)"
+          fi
+          
+          echo "VERSION=${VERSION}"
+          docker build --build-arg VERSION="${VERSION}" -t agent-memory:latest .
+
+      - name: Test Docker image with SQLite backend
+        run: |
+          docker run --rm agent-memory:latest --help
+          docker run --rm -v agent_memory_data:/home/appuser/.agent_memory agent-memory:latest remember "test" "test response"
+          docker run --rm -v agent_memory_data:/home/appuser/.agent_memory agent-memory:latest resolve "test"
+
+      - name: Test Docker image with ChromaDB backend
+        run: |
+          docker run --rm -v agent_memory_chromadb:/home/appuser/.agent_memory agent-memory:latest remember "test" "test response" --backend chromadb
+          docker run --rm -v agent_memory_chromadb:/home/appuser/.agent_memory agent-memory:latest resolve "test" --backend chromadb
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: [test, benchmark]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4.2.2
+
+      - name: Set up Python
+        uses: actions/setup-python@v5.5.0
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip build twine
+
+      - name: Build package
+        run: |
+          # For tag releases, use clean version without local identifier
+          VERSION=${GITHUB_REF_NAME#v}
+          SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION} python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          twine upload dist/*
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

agent_memory_sdk-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.env
+
+# Chroma / memory data
+.agent_memory/
+.agent_memory_demo/
+
+# IDE
+.idea/
+.vscode/
+
+# Test / build
+.pytest_cache/
+dist/
+build/
+
+.agent_memory/
+.agent_memory_demo/
+.pytest_cache/

agent_memory_sdk-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+# Pre-commit hooks for Agent Memory
+# Install: pip install pre-commit && pre-commit install
+
+repos:
+  # Ruff - Fast Python linter and formatter
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.0
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  # MyPy - Static type checking
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-requests, pydantic, chromadb]
+        args: [--ignore-missing-imports, agent_memory/]
+
+  # Check for common issues
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-merge-conflict
+      - id: debug-logger
+      - id: detect-private-key
+
+  # Bandit - Security linting
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.7.8
+    hooks:
+      - id: bandit
+        args: [-r, agent_memory/, -ll]
+        exclude: tests/
+
+  # Check for TODO/FIXME comments
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-case-conflict
+      - id: mixed-line-ending
+        args: [--fix=lf]

agent_memory_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- SQLite backend (`SqliteMemoryStore`) as default lightweight storage
+- Async API support (`aremember`, `aresolve`, `alist`, `aget`, `aforget`, `aarchive`, `acleanup`, `astats`, `aconsolidate`)
+- Backend selection via `backend` parameter in `Memory` constructor (`"chromadb"` or `"sqlite"`)
+- Comprehensive test coverage for both ChromaDB and SQLite backends
+- Package distribution configuration (wheel, sdist)
+- Docker support with both backends
+
+### Changed
+- **Default backend changed from ChromaDB to SQLite** for lightweight deployments
+- Version bumped to `0.1.0-alpha` (was incorrectly `0.3.0` in code/docs)
+- Updated roadmap to reflect completed features
+
+### Fixed
+- Version inconsistency across `pyproject.toml`, `agent_memory/__init__.py`, and `README.md`
+- Clean code principles and SOLID OOP compliance across all modules
+
+## [0.1.0-alpha] - 2026-06-28
+
+### Added
+- Initial release of Agent Memory
+- Decision-based memory layer (Replay / Restore / Verify / None)
+- Hybrid retrieval: BM25 keyword search + Vector semantic search with RRF fusion
+- Multi-factor scoring policy (semantic 70%, recency 15%, confidence 20%, frequency 10%)
+- Structured memory with types (conversation, fact, workflow, document, tool_output, code, summary, preference)
+- Scoped memory (session, user, project, workspace, team, global)
+- TTL support with flexible duration strings (e.g., "30d", "2h")
+- Full observability via `decision.explain()`
+- CLI with remember, resolve, stats, benchmark, eval, cleanup commands
+- MCP server integration for Cursor, VS Code, and other MCP clients
+- Docker support with multi-stage build
+- Comprehensive documentation (architecture, benchmarks, examples, FAQ, getting started, memory model, policies)
+- Benchmark and evaluation datasets (coding_agent, customer_support, research_agent)
+- CI/CD pipeline with GitHub Actions
+- Pre-commit hooks (ruff, mypy, black)
+
+### Security
+- No known vulnerabilities
+
+---
+
+## Release Notes Template
+
+### [X.Y.Z] - YYYY-MM-DD
+
+#### Added
+- New features
+
+#### Changed
+- Changes in existing functionality
+
+#### Deprecated
+- Soon-to-be removed features
+
+#### Removed
+- Removed features
+
+#### Fixed
+- Bug fixes
+
+#### Security
+- Security fixes

agent_memory_sdk-0.1.0/Dockerfile

@@ -0,0 +1,77 @@
+# Multi-stage Docker build for agent-memory
+FROM python:3.11-slim AS builder
+
+# Build argument for version (passed from CI)
+ARG VERSION=0.0.0
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install build backend dependencies (required for --no-build-isolation)
+RUN pip install --no-cache-dir hatchling hatch-vcs
+
+# Set working directory
+WORKDIR /app
+
+# Copy project files
+COPY pyproject.toml README.md ./
+COPY agent_memory/ ./agent_memory/
+COPY mcp_server/ ./mcp_server/
+
+# Set version for hatch-vcs (since .git is not available in build context)
+ENV SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION}
+
+# Debug: print version
+RUN echo "Building version: ${VERSION}" && echo "SETUPTOOLS_SCM_PRETEND_VERSION=${SETUPTOOLS_SCM_PRETEND_VERSION}"
+
+# Install runtime dependencies including chromadb (without editable to avoid VCS version detection)
+RUN SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION} pip install --no-cache-dir --no-build-isolation ".[chromadb]"
+
+# Runtime stage - use slim for pip availability, but keep it minimal
+FROM python:3.11-slim AS runtime
+
+# Build argument for version (passed from CI)
+ARG VERSION=0.0.0
+
+# Set version for hatch-vcs in runtime stage too
+ENV SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION}
+
+# Install runtime dependencies only
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libstdc++6 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user
+RUN useradd --create-home --shell /bin/bash appuser
+
+# Set working directory to user's home directory
+WORKDIR /home/appuser
+
+# Copy installed packages from builder (only runtime deps)
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy source code and install in runtime (without dev dependencies)
+COPY --from=builder /app/agent_memory ./agent_memory
+COPY --from=builder /app/mcp_server ./mcp_server
+COPY --from=builder /app/pyproject.toml ./pyproject.toml
+COPY --from=builder /app/README.md ./README.md
+
+# Install package in runtime (without dev dependencies, with build isolation for build backend)
+RUN SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION} pip install --no-cache-dir --no-deps .
+
+# Create data directory for persistence
+RUN mkdir -p /home/appuser/.agent_memory && chown -R appuser:appuser /home/appuser
+
+# Switch to non-root user
+USER appuser
+ENV HOME=/home/appuser
+ENV AGENT_MEMORY_DIR=/home/appuser/.agent_memory
+
+# Expose MCP server port (if needed)
+EXPOSE 8000
+
+# Set entrypoint
+ENTRYPOINT ["agent-memory"]

agent_memory_sdk-0.1.0/LICENSE

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

agent_memory_sdk-0.1.0/Makefile

@@ -0,0 +1,132 @@
+# Makefile for Agent Memory Development
+
+.PHONY: help install test lint typecheck format benchmark eval clean docker-build docker-run docker-mcp
+
+# Default target
+help:
+	@echo "Agent Memory - Development Commands"
+	@echo ""
+	@echo "Setup:"
+	@echo "  install       Install package in development mode with dev dependencies"
+	@echo "  install-ci    Install for CI (no dev dependencies)"
+	@echo ""
+	@echo "Testing:"
+	@echo "  test          Run all tests"
+	@echo "  test-v        Run tests with verbose output"
+	@echo "  test-cov      Run tests with coverage report"
+	@echo ""
+	@echo "Code Quality:"
+	@echo "  lint          Run ruff linter"
+	@echo "  typecheck     Run mypy type checker"
+	@echo "  format        Format code with ruff"
+	@echo "  check         Run lint + typecheck"
+	@echo ""
+	@echo "Benchmarks & Evaluation:"
+	@echo "  benchmark     Run quick benchmark"
+	@echo "  benchmark-full Run full benchmark with seeded data"
+	@echo "  eval          Run evaluation datasets"
+	@echo ""
+	@echo "Docker:"
+	@echo "  docker-build  Build Docker image"
+	@echo "  docker-run    Run CLI in Docker"
+	@echo "  docker-mcp    Run MCP server in Docker"
+	@echo "  docker-compose-up  Start services with docker-compose"
+	@echo "  docker-compose-down Stop services"
+	@echo ""
+	@echo "Maintenance:"
+	@echo "  clean         Remove build artifacts and cache"
+	@echo "  reset-db      Reset ChromaDB database"
+
+# Installation
+install:
+	pip install -e ".[dev]"
+
+install-ci:
+	pip install -e .
+
+# Testing
+test:
+	python -m pytest tests/ -v
+
+test-v:
+	python -m pytest tests/ -vv --tb=long
+
+test-cov:
+	python -m pytest tests/ --cov=agent_memory --cov-report=term-missing --cov-report=html
+
+# Code Quality
+lint:
+	ruff check agent_memory/ tests/
+
+typecheck:
+	mypy agent_memory/ --ignore-missing-imports
+
+format:
+	ruff format agent_memory/ tests/
+
+check: lint typecheck
+
+# Benchmarks & Evaluation
+benchmark:
+	agent-memory benchmark
+
+benchmark-full:
+	agent-memory benchmark --seed --repeat 3
+
+eval:
+	agent-memory eval
+
+# Docker
+docker-build:
+	docker build -t agent-memory:latest .
+
+docker-run:
+	docker run --rm -v agent_memory_data:/home/appuser/.agent_memory agent-memory:latest agent-memory $(ARGS)
+
+docker-mcp:
+	docker run -d --name agent-memory-mcp \
+		-v agent_memory_data:/home/appuser/.agent_memory \
+		-p 8000:8000 \
+		agent-memory:latest agent-memory-mcp
+
+docker-compose-up:
+	docker-compose up -d
+
+docker-compose-down:
+	docker-compose down
+
+docker-compose-logs:
+	docker-compose logs -f
+
+# Maintenance
+clean:
+	rm -rf build/ dist/ *.egg-info/ .pytest_cache/ .mypy_cache/ .ruff_cache/ htmlcov/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete
+
+reset-db:
+	rm -rf .agent_memory .agent_memory_demo
+	docker volume rm agent_memory_data 2>/dev/null || true
+
+# Development shortcuts
+dev: install
+	@echo "Development environment ready!"
+	@echo "Run 'make test' to run tests"
+	@echo "Run 'make benchmark' to run benchmarks"
+
+# Run example
+example:
+	python examples/basic_usage.py
+
+# Run CLI help
+cli-help:
+	agent-memory --help
+
+# Install pre-commit hooks
+pre-commit-install:
+	pip install pre-commit
+	pre-commit install
+
+# Run pre-commit on all files
+pre-commit-run:
+	pre-commit run --all-files