supermem 0.3.0__tar.gz

supermem-0.3.0/.dockerignore

@@ -0,0 +1,36 @@
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+*.egg-info/
+dist/
+build/
+
+# Tests
+tests/
+.pytest_cache/
+.coverage
+coverage.xml
+
+# CI
+.github/
+
+# Docs
+docs/
+
+# Dev
+.memory_path
+.filters
+.mlx_model_name
+mcp.json
+debug/
+tmp_work/
+
+# OS
+.DS_Store

supermem-0.3.0/.env.example

@@ -0,0 +1,164 @@
+# supermem — Environment Variables
+# ==============================================================================
+# Copy this file to .env and fill in values as needed.
+# .env is gitignored and will never be committed.
+#
+# Quick start (3 vars minimum):
+#   SUPERMEM_VAULT_PATH=~/notes
+#   SUPERMEM_LLM_PROVIDER=openrouter
+#   OPENROUTER_API_KEY=sk-or-...
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# 1. Core Setup (required)
+# ══════════════════════════════════════════════════════════════════════════════
+
+# LLM provider backend. Controls which API / server supermem uses for tier-4
+# agent fallback and compression.
+#   openrouter  → cloud (OpenRouter, no GPU needed)
+#   claude      → cloud (Anthropic direct)
+#   ollama      → local (Ollama server)
+#   vllm        → local (vLLM server with GPU)
+#   lmstudio    → local (LM Studio)
+SUPERMEM_LLM_PROVIDER=openrouter
+
+# Model string passed to the provider above. Leave blank to use each
+# provider's default (claude-sonnet-4 for OpenRouter, llama3.2 for Ollama,
+# driaforall/mem-agent for vLLM, claude-sonnet-4-5 for Anthropic).
+# Examples: openai/gpt-4o-mini, llama3.2, claude-opus-4-5
+SUPERMEM_LLM_MODEL=
+
+# Absolute path to your markdown vault directory. This is where supermem
+# reads and indexes your notes.
+# Default: reads .memory_path file in the repo root, falls back to ./memory/mcp-server
+SUPERMEM_VAULT_PATH=
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# 2. Provider-specific API keys & hosts
+# ══════════════════════════════════════════════════════════════════════════════
+
+# ── OpenRouter (required when SUPERMEM_LLM_PROVIDER=openrouter) ──────────────
+# Get a key at https://openrouter.ai/keys
+OPENROUTER_API_KEY=
+# Optional: custom base URL for proxies/gateways (default: https://openrouter.ai/api/v1)
+# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+
+# ── Anthropic (required when SUPERMEM_LLM_PROVIDER=claude) ──────────────────
+# Get a key at https://console.anthropic.com/
+ANTHROPIC_API_KEY=
+
+# ── Ollama (used when SUPERMEM_LLM_PROVIDER=ollama) ─────────────────────────
+OLLAMA_HOST=http://localhost:11434
+
+# ── vLLM (used when SUPERMEM_LLM_PROVIDER=vllm) ─────────────────────────────
+VLLM_HOST=0.0.0.0
+VLLM_PORT=8000
+
+# ── LM Studio (used when SUPERMEM_LLM_PROVIDER=lmstudio) ────────────────────
+LMSTUDIO_HOST=http://localhost:1234
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# 3. Storage paths
+# ══════════════════════════════════════════════════════════════════════════════
+
+# SQLite database path (default: ~/.supermem/supermem.db)
+# SUPERMEM_DB_PATH=~/.supermem/supermem.db
+
+# Kuzu embedded graph database path (default: ~/.supermem/graph)
+# Tier 2 — optional. Install with: pip install kuzu
+# SUPERMEM_KUZU_PATH=~/.supermem/graph
+
+# ChromaDB vector store path (default: ~/.supermem/chroma)
+# Tier 3 — requires SUPERMEM_VECTOR=true below
+# SUPERMEM_CHROMA_PATH=~/.supermem/chroma
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# 4. Feature flags
+# ══════════════════════════════════════════════════════════════════════════════
+
+# Enable ChromaDB vector similarity tier (tier 3). Requires:
+#   pip install chromadb sentence-transformers
+# Default: false
+SUPERMEM_VECTOR=false
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# 5. Retrieval tuning
+# ══════════════════════════════════════════════════════════════════════════════
+
+# Minimum results before short-circuiting. If tier 1 (FTS5) returns at least
+# this many matches, tiers 2–4 are skipped entirely.
+# Default: 3
+# SUPERMEM_MIN_RESULTS=3
+
+# Default tier limit for hybrid search (1–4). Lower = faster but less thorough.
+# Default: 4
+# SUPERMEM_DEFAULT_TIER_LIMIT=4
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# 6. Agent / sandbox limits
+# ══════════════════════════════════════════════════════════════════════════════
+
+# Max tool-calling turns the LLM agent can take before giving up.
+# Default: 20
+# SUPERMEM_MAX_TOOL_TURNS=20
+
+# Timeout in seconds for the agent's Python sandbox execution.
+# Default: 20
+# SUPERMEM_SANDBOX_TIMEOUT=20
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# 7. Compression & expiry
+# ══════════════════════════════════════════════════════════════════════════════
+
+# Number of observations written before the LLM compression pass runs.
+# Default: 50
+# SUPERMEM_COMPRESS_EVERY=50
+
+# TTL for regular observations in days (0 = never expire).
+# Default: 90
+# SUPERMEM_OBS_TTL_DAYS=90
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# 8. HTTP dashboard & API (optional — requires supmem serve --worker)
+# ══════════════════════════════════════════════════════════════════════════════
+
+# Port for the HTTP dashboard and REST API. Access at http://localhost:37777
+# Default: 37777
+# SUPERMEM_WORKER_PORT=37777
+
+# Bind address for the HTTP worker.
+# Default: 127.0.0.1
+# SUPERMEM_WORKER_HOST=127.0.0.1
+
+# Bearer token for HTTP API authentication. When set, all endpoints require:
+#   Authorization: Bearer <SUPERMEM_API_KEY>
+# When left empty, auth is disabled (convenient for local use).
+# SUPERMEM_API_KEY=
+
+# Rate limit in requests per minute for the HTTP API.
+# Default: 60
+# SUPERMEM_RATE_LIMIT=60
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# 9. Logging & transport
+# ══════════════════════════════════════════════════════════════════════════════
+
+# FastMCP log level. Set to DEBUG for verbose output when troubleshooting.
+# Options: DEBUG, INFO, WARNING, ERROR
+# Default: INFO
+FASTMCP_LOG_LEVEL=INFO
+
+# MCP transport protocol. Only relevant when running supmem serve.
+#   stdio  → Claude Desktop and other stdio-based MCP clients
+#   http   → ChatGPT and HTTP-based MCP clients
+#   sse    → Server-Sent Events transport
+# Default: stdio
+MCP_TRANSPORT=stdio

supermem-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,57 @@
+---
+name: Bug report
+about: Something is broken
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+
+A clear and concise description of what the bug is.
+
+## To reproduce
+
+Steps to reproduce:
+1. Run `...`
+2. Ask `...`
+3. See error
+
+## Expected behaviour
+
+What you expected to happen.
+
+## Actual behaviour
+
+What actually happened. Include the full error message or unexpected output.
+
+## Logs
+
+Enable debug logging and paste the relevant output:
+
+```bash
+FASTMCP_LOG_LEVEL=DEBUG make serve-mcp
+```
+
+```
+[paste logs here]
+```
+
+## Environment
+
+- OS: [e.g. macOS 14.5, Ubuntu 22.04]
+- Python version: `python --version`
+- uv version: `uv --version`
+- Model used: [e.g. mem-agent-mlx-4bit, vLLM]
+- AI client: [e.g. Claude Desktop 1.x, LM Studio 0.x, ChatGPT]
+- Transport: [stdio / http / sse]
+
+## Memory setup
+
+- Memory directory size (approx):
+- Number of files in memory:
+- Connector used to import (if any):
+
+## Additional context
+
+Any other context about the problem.

supermem-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,30 @@
+---
+name: Feature request
+about: Suggest a new connector, integration, or capability
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## What problem does this solve?
+
+A clear description of the problem or gap this feature addresses.
+
+Example: *"I want to import my Obsidian vault directly, but there's no connector for it."*
+
+## Proposed solution
+
+Describe what you'd like to see added.
+
+## Alternatives considered
+
+Any other approaches you considered and why you ruled them out.
+
+## Are you willing to implement this?
+
+- [ ] Yes, I can open a PR
+- [ ] No, I'm requesting it from maintainers
+
+## Additional context
+
+Any screenshots, links, or context that would help.

supermem-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,41 @@
+## Summary
+
+What does this PR do? (1–3 sentences)
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature (new connector, integration, or agent capability)
+- [ ] Refactor / cleanup
+- [ ] Documentation
+- [ ] Tests only
+
+## Changes
+
+-
+-
+-
+
+## Testing
+
+How did you test this?
+
+- [ ] Added / updated unit tests in `tests/`
+- [ ] Tested manually with Claude Desktop
+- [ ] Tested manually with LM Studio
+- [ ] Tested manually with ChatGPT
+- [ ] Tested the CLI (`make chat-cli`)
+
+## For new connectors
+
+- [ ] Inherits from `BaseMemoryConnector`
+- [ ] Implements `extract_data()`, `organize_data()`, `generate_memory_files()`
+- [ ] Registered in `memory_connect.py`
+- [ ] README updated with usage examples
+- [ ] At least one test in `tests/`
+
+## Checklist
+
+- [ ] `uv run pytest tests/ -v` passes
+- [ ] `uv run black .` applied
+- [ ] No secrets or personal data committed

supermem-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,121 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+jobs:
+  # ── Lint + type-check + test ───────────────────────────────────────────────
+  check:
+    name: Lint, type-check, test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Ruff lint
+        run: uv run ruff check supermem/ agent/ mcp_server/ --output-format=github || true
+
+      - name: Check formatting (black)
+        run: uv run black --check .
+
+      - name: mypy type-check
+        run: uv run mypy supermem/ --ignore-missing-imports --no-error-summary
+        continue-on-error: true
+
+      - name: pytest with coverage
+        run: |
+          uv run pytest tests/ \
+            --cov=supermem \
+            --cov=agent \
+            --cov-report=term-missing \
+            --cov-report=xml \
+            --cov-fail-under=60
+
+      - name: Upload coverage report
+        uses: codecov/codecov-action@v4
+        if: always()
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false
+
+  # ── Docker build (on tag push only) ───────────────────────────────────────
+  docker:
+    name: Build and push Docker image
+    runs-on: ubuntu-latest
+    needs: check
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  # ── PyPI publish (on tag push only) ────────────────────────────────────────
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: check
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

supermem-0.3.0/.gitignore

@@ -0,0 +1,48 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+data_gen/instances/
+
+# Virtual environments
+.venv
+
+# .env
+.env
+
+# debug
+debug/
+
+# lock files (keep uv.lock committed for reproducibility)
+*.lock
+!uv.lock
+
+# memory (generated, contains personal data)
+memory/
+local-memory/
+
+# tmp
+tmp_work/
+
+# .DS_Store
+.DS_Store
+**/.DS_Store
+
+# mcp.json
+mcp.json
+
+# .memory_path
+.memory_path
+
+# .filters
+.filters
+
+# .mlx_model_name
+.mlx_model_name
+
+## start_server.sh
+**/start_server.sh
+.coverage

supermem-0.3.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# 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).
+
+## [0.2.0] - 2026-04-07
+
+### Added
+- **Ambient memory injection** via Claude Code hook system — automatically surfaces relevant observations during user prompts without requiring explicit memory queries
+- **TTL-based observation expiry** — configure retention via `SUPERMEM_OBS_TTL_DAYS` (default: 90 days); automatic cleanup on startup and via worker API
+- **Parallel retrieval tiers** — hybrid retrieval (FTS5 → graph → vector → agent) now runs in parallel for sub-100ms queries
+- **New hooks system** (`supermem/hooks/`) — `inject.py` reads user prompts from stdin, searches local SQLite, injects observations as system context
+- **ServerContext extraction** — refactored MCP server to isolate initialization and startup failure handling
+- **Comprehensive test coverage** — 522 new lines of MCP server tests, database tests, vault indexer tests; all observation expiry paths covered
+
+### Changed
+- **Rate limiter** — split per-user and per-endpoint limits for better control and clearer semantics
+- **Vault indexer** — mtime-skip optimization to reduce redundant indexing; `get_entity_last_indexed` now cached
+- **Startup robustness** — clear separation of startup failures (auth, db, config) vs. runtime errors
+
+### Fixed
+- Black formatting alignment across all Python files
+
+## [0.1.0] - 2025-02-25
+
+### Added
+- Initial release: supermem v2 — four-tier retrieval architecture (FTS5 → graph → vector → agent)
+- MCP server (stdio + HTTP transports) exposing agent as memory tool
+- Hybrid storage: SQLite (FTS5), Kuzu (graph), Chroma (vector)
+- Session tracking and observation recording
+- Memory import connectors (ChatGPT, Notion, Nuclino, GitHub, Google Docs)
+- `supermem` CLI with serve, chat, backup, restore, connect commands
+- Worker HTTP API (`:37777`) for search, indexing, health checks