memable 0.1.1__tar.gz

memable-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: pytest tests/unit -v
+
+      - name: Run integration tests
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          DATABASE_URL: postgresql://test:test@localhost:5432/test
+        run: pytest tests/integration -v
+        # Skip if no API key (fork PRs won't have secrets)
+        if: env.OPENAI_API_KEY != ''
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff mypy
+
+      - name: Run ruff
+        run: ruff check src/
+
+      - name: Run mypy
+        run: mypy src/ --ignore-missing-imports
+        continue-on-error: true  # Don't fail on type errors yet

memable-0.1.1/.github/workflows/pages.yml

@@ -0,0 +1,61 @@
+name: Deploy Landing Page
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'landing/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'pnpm'
+          cache-dependency-path: landing/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: landing
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        working-directory: landing
+        run: pnpm build
+        env:
+          NEXT_PUBLIC_BASE_PATH: /memable
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: landing/out
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

memable-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    concurrency: release
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install python-semantic-release
+        run: pip install python-semantic-release
+
+      - name: Python Semantic Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to GitHub Releases
+        uses: python-semantic-release/upload-to-gh-release@main
+        if: steps.release.outputs.released == 'true'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}

memable-0.1.1/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+
+# Environments
+.env
+.env.local
+*.env
+
+# OS
+.DS_Store
+Thumbs.db
+
+.claude/

memable-0.1.1/CHANGELOG.md

@@ -0,0 +1,20 @@
+# 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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-06
+
+### Added
+- Memory schema with durability tiers (core/situational/episodic)
+- Version chains for contradiction handling with full audit trail
+- Temporal validity (valid_from/valid_until) for time-bounded memories
+- PostgresStore wrapper with semantic search via pgvector
+- LLM-based memory extraction with automatic durability classification
+- Contradiction detection and resolution
+- Memory consolidation strategies (prune, decay, summarize, dedupe)
+- LangGraph nodes (retrieve_memories, store_memories, consolidate_memories)
+- Pre-built memory graph for quick integration
+- Example app with Neon integration

memable-0.1.1/CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Development Commands
+
+```bash
+# Install for development
+pip install -e ".[dev]"
+
+# Run all tests
+pytest
+
+# Run unit tests only (no external deps)
+pytest tests/unit -m unit
+
+# Run integration tests (requires Docker with pgvector or DATABASE_URL)
+pytest tests/integration -m integration
+
+# Run a single test file
+pytest tests/unit/test_schema.py -v
+
+# Run performance tests (requires OPENAI_API_KEY)
+pytest tests/performance -v -s
+
+# Lint and format
+ruff check src tests
+ruff format src tests
+
+# Type check
+mypy src
+```
+
+## Environment Variables
+
+- `OPENAI_API_KEY` - Required for embeddings
+- `DATABASE_URL` - PostgreSQL connection string (for integration tests and production)
+- `MEMORY_DB_PATH` - SQLite path when using SQLite backend
+
+## Architecture Overview
+
+memento-ai is a semantic memory library for LangGraph agents with three storage backends.
+
+### Core Components
+
+**Schema (`src/memento_ai/schema.py`)**
+- `Memory` - Main memory object with durability tiers (core/situational/episodic), temporal validity, version chains, and MemoryType categorization
+- `MemoryCreate`/`MemoryUpdate`/`MemoryQuery` - Input/query types
+- Version chains track supersedes/superseded_by for contradiction handling
+
+**Store (`src/memento_ai/store.py`)**
+- `SemanticMemoryStore` - High-level API wrapping backend stores
+- Factory functions: `build_store()` (auto-detect), `build_postgres_store()`, `build_sqlite_store()`, `build_duckdb_store()`
+- All stores use context managers for connection lifecycle
+
+**Backends (`src/memento_ai/backends/`)**
+- `BaseStore` - Abstract protocol defining put/get/delete/search operations
+- `PostgresStore` - Production backend using pgvector
+- `SQLiteStore` - Dev/testing backend using sqlite-vec
+- `DuckDBStore` - Analytics backend with native vector similarity
+- Factory in `factory.py` auto-selects backend from URL scheme
+
+**LangGraph Integration**
+- `nodes.py` - Pre-built nodes: `retrieve_memories_node`, `store_memories_node`, `consolidate_memories_node`
+- `graph.py` - `build_memory_graph()` creates a ready-to-use graph with retrieve -> LLM -> store flow
+
+**Supporting Modules**
+- `extraction.py` - LLM-based memory extraction from conversations
+- `contradiction.py` - Detect and resolve conflicting memories via version chains
+- `consolidation.py` - Decay, summarize, and prune old memories
+- `retrieval.py` - Multi-scope retrieval with priority merging
+
+### Key Patterns
+
+- Namespaces are tuples: `("org_id", "user_id", "scope")` for hierarchical scoping
+- Version chains preserve history: old memories get `superseded_by`, new ones get `supersedes`
+- Temporal validity via `valid_from`/`valid_until` with automatic filtering
+- All backends implement the same `BaseStore` interface for swappable storage
+
+### Testing
+
+Integration tests use testcontainers with `pgvector/pgvector:pg16` image. Pull first:
+```bash
+docker pull pgvector/pgvector:pg16
+```

memable-0.1.1/LICENSE

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

memable-0.1.1/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: memable
+Version: 0.1.1
+Summary: Reusable semantic memory library for LangGraph agents with PostgreSQL/pgvector and SQLite backends
+Project-URL: Repository, https://github.com/joelash/memento-ai
+Author: Joel Ash
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,langgraph,memory,pgvector,postgres,semantic,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langchain-openai>=0.3.0
+Requires-Dist: langgraph-checkpoint-postgres>=2.0.0
+Requires-Dist: langgraph>=0.2.0
+Requires-Dist: psycopg[binary]>=3.1.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: all
+Requires-Dist: memento-ai[dev,duckdb,sqlite]; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: duckdb>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: testcontainers[postgres]>=4.0.0; extra == 'dev'
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=1.0.0; extra == 'duckdb'
+Provides-Extra: sqlite
+Requires-Dist: sqlite-vec>=0.1.0; extra == 'sqlite'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/memable-hero.png" alt="memable - AI memory that never forgets" width="600">
+</p>
+
+<h1 align="center">memable 🐘</h1>
+
+<p align="center">
+  <em>Long-term semantic memory for AI agents. Elephants never forget.</em>
+</p>
+
+---
+
+Drop-in long-term memory with:
+
+- **Durability tiers** — core facts vs situational context vs episodic memories
+- **Temporal awareness** — validity windows, expiry, recency weighting
+- **Version chains** — audit trail for memory updates with contradiction handling
+- **Scoped namespaces** — org/user/project hierarchies with priority merging
+- **Memory consolidation** — decay, summarize, and prune old memories
+- **LangGraph integration** — ready-to-use nodes for retrieve/store/consolidate
+
+## Need Help?
+
+**I'll add production-grade memory to your AI agent in 1-2 weeks.**
+
+- 📞 **Consult** ($500) — 2-hour architecture deep-dive
+- 🛠️ **Implementation** ($3-5k) — Full memory system, integrated + tested
+
+[Book a Call →](https://calendar.superhuman.com/book/11SzDnK01g1VgPEI2w/FtV5Q)
+
+---
+
+## Installation
+
+```bash
+pip install memable
+```
+
+Or for development:
+
+```bash
+git clone https://github.com/joelash/memable
+cd memable
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from memable import build_postgres_store
+from memable.graph import build_memory_graph
+
+# Connect to your Neon/Postgres DB (context manager handles connection lifecycle)
+with build_postgres_store("postgresql://user:pass@host:5432/dbname") as store:
+    store.setup()  # Run migrations (once)
+
+    # Build a graph with memory baked in
+    graph = build_memory_graph()
+    compiled = graph.compile(store=store.raw_store)
+
+    # Run it
+    config = {"configurable": {"user_id": "user_123"}}
+    result = compiled.invoke(
+        {"messages": [{"role": "user", "content": "I'm Joel, I live in Wheaton."}]},
+        config=config,
+    )
+```
+
+## Memory Schema
+
+Each memory item includes:
+
+```python
+{
+    "text": "User lives in Wheaton, IL",
+    "durability": "core",           # core | situational | episodic
+    "valid_from": "2026-02-06",     # when this became true
+    "valid_until": None,            # null = permanent
+    "confidence": 0.95,
+    "source": "explicit",           # explicit | inferred
+    "supersedes": None,             # UUID of memory this replaces (version chain)
+    "superseded_by": None,          # UUID of memory that replaced this
+}
+```
+
+## Durability Tiers
+
+| Tier | Description | Example | Default TTL |
+|------|-------------|---------|-------------|
+| `core` | Stable facts about the user | "Name is Joel", "Prefers dark mode" | Never expires |
+| `situational` | Temporary context | "Visiting Ohio this week" | Explicit end date |
+| `episodic` | Things that happened | "We discussed the API design" | 30 days, decays |
+
+## Features
+
+### Version Chains (Contradiction Handling)
+
+When a memory contradicts an existing one, we don't delete — we create a version chain:
+
+```python
+# Original: "User lives in Wheaton"
+# New info: "User moved to Austin"
+
+# Result:
+# - Old memory gets superseded_by = new_memory_id
+# - New memory gets supersedes = old_memory_id
+# - Retrieval only returns current (non-superseded) memories
+# - Audit trail preserved for debugging
+```
+
+### Scoped Namespaces
+
+```python
+# Retrieval merges across scopes with priority
+retrieve_memories(
+    store=store,
+    scopes=[
+        ("org_123", "user_456", "preferences"),  # highest priority
+        ("org_123", "shared"),                    # org-wide fallback
+    ],
+    query="user preferences",
+)
+```
+
+### Memory Consolidation
+
+```python
+from memable import consolidate_memories
+
+# Periodic cleanup job
+consolidate_memories(
+    store=store,
+    user_id="user_123",
+    strategy="summarize_and_prune",
+    older_than_days=7,
+)
+```
+
+## LangGraph Nodes
+
+Pre-built nodes for your graph:
+
+```python
+from memable.nodes import (
+    retrieve_memories_node,
+    store_memories_node,
+    consolidate_memories_node,
+)
+
+builder = StateGraph(MessagesState)
+builder.add_node("retrieve", retrieve_memories_node)
+builder.add_node("llm", your_llm_node)
+builder.add_node("store", store_memories_node)
+
+builder.add_edge(START, "retrieve")
+builder.add_edge("retrieve", "llm")
+builder.add_edge("llm", "store")
+builder.add_edge("store", END)
+```
+
+## Performance & Costs
+
+### Storage Requirements
+
+| Scale | Memories | SQLite | DuckDB | Postgres |
+|-------|----------|--------|--------|----------|
+| Light user | 100 | ~700 KB | ~3 MB | ~700 KB |
+| Regular user | 1,000 | ~7 MB | ~30 MB | ~7 MB |
+| Heavy user | 10,000 | ~70 MB | ~300 MB | ~70 MB |
+| Power user | 100,000 | ~700 MB | ~3 GB | ~700 MB |
+
+*Embeddings dominate storage: 1536 dims × 4 bytes = ~6KB per memory*
+
+### API Costs (text-embedding-3-small)
+
+| Usage | Daily Tokens | Daily Cost | Monthly Cost |
+|-------|--------------|------------|--------------|
+| Light (100 adds, 500 searches) | 7,000 | $0.0001 | $0.00 |
+| Medium (500 adds, 2,000 searches) | 30,000 | $0.0006 | $0.02 |
+| Heavy (2,000 adds, 10,000 searches) | 140,000 | $0.0028 | $0.08 |
+
+### Extraction Costs (gpt-4.1-mini)
+
+If using LLM-based memory extraction:
+
+| Usage | Daily Cost | Monthly Cost |
+|-------|------------|--------------|
+| Light (50 extractions) | $0.007 | $0.20 |
+| Medium (200 extractions) | $0.027 | $0.81 |
+| Heavy (1,000 extractions) | $0.135 | $4.05 |
+
+**Total cost for a typical agent (100 conversations/day):** ~$0.08-0.50/month
+
+Run `pytest tests/performance/ -v -s` to benchmark on your hardware.
+
+## Configuration
+
+Environment variables:
+
+```bash
+OPENAI_API_KEY=sk-...           # For embeddings
+DATABASE_URL=postgresql://...    # Postgres connection
+```
+
+## Multi-Tenant / Schema Isolation
+
+For multi-tenant deployments where each customer needs isolated data, you can use PostgreSQL schemas:
+
+```python
+from memable import build_store
+
+# Each tenant gets their own schema
+with build_store("postgresql://...", schema="customer_123") as store:
+    store.setup()  # Creates tables in customer_123 schema
+    store.add(namespace, memory)
+```
+
+**Requirements:**
+- The schema must already exist in the database (`CREATE SCHEMA customer_123;`)
+- Tables will be created within that schema when `setup()` is called
+- Each schema has its own isolated set of tables
+
+### Database Tables
+
+memable uses LangGraph's PostgresStore under the hood, which creates:
+
+| Table | Purpose |
+|-------|---------|
+| `store` | Memory documents with metadata |
+| `store_vectors` | pgvector embeddings for semantic search |
+| `store_migrations` | Migration version tracking |
+
+**Note:** Table names are currently fixed by LangGraph. If you need custom table names (e.g., prefixes/suffixes), use schema-based isolation instead, or run each app in a separate PostgreSQL schema.
+
+**Alternative pattern:** For apps that already use schema-per-tenant, you could combine with a suffix:
+```sql
+-- Example: customer schemas with memory suffix
+CREATE SCHEMA customer_123_memories;
+```
+```python
+with build_store("postgresql://...", schema="customer_123_memories") as store:
+    store.setup()
+```
+
+## License
+
+MIT