synapto 0.1.0__tar.gz

synapto-0.1.0/.dockerignore

@@ -0,0 +1,13 @@
+.venv/
+venv/
+.git/
+.github/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.env
+.DS_Store

synapto-0.1.0/.env.example

@@ -0,0 +1,25 @@
+# Synapto — environment variables
+# Copy this file to .env and adjust values for your setup.
+# All variables are optional — sensible defaults are used when unset.
+
+# PostgreSQL connection string
+SYNAPTO_PG_DSN=postgresql://localhost/synapto
+
+# Redis URL
+SYNAPTO_REDIS_URL=redis://localhost:6379/0
+
+# Default tenant (project/codebase scope for memory isolation)
+SYNAPTO_DEFAULT_TENANT=default
+
+# Embedding provider: leave empty for auto-select
+#   - auto-selects OpenAI if OPENAI_API_KEY is set, otherwise sentence-transformers (local)
+#   - valid values: sentence-transformers, openai
+SYNAPTO_EMBEDDING_PROVIDER=
+
+# Embedding model override (provider-specific)
+#   - sentence-transformers default: multi-qa-MiniLM-L6-cos-v1
+#   - openai default: text-embedding-3-small
+SYNAPTO_EMBEDDING_MODEL=
+
+# OpenAI API key (optional — only needed if using OpenAI embeddings)
+OPENAI_API_KEY=

synapto-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: "[bug] "
+labels: bug
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to Reproduce
+
+1. ...
+2. ...
+3. ...
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include error messages or logs if available.
+
+## Environment
+
+- Synapto version: 
+- Python version: 
+- OS: 
+- PostgreSQL version: 
+- MCP client (Claude Code, Cursor, etc.): 

synapto-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: "[feature] "
+labels: enhancement
+---
+
+## Problem
+
+What problem does this feature solve? Why is it needed?
+
+## Proposed Solution
+
+Describe your ideal solution.
+
+## Alternatives Considered
+
+Any other approaches you've thought about.
+
+## Additional Context
+
+Any extra context, mockups, or references.

synapto-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## Summary
+
+Brief description of the changes.
+
+## Related Issues
+
+Closes #
+
+## Changes
+
+- 
+
+## Checklist
+
+- [ ] Tests added/updated for new functionality
+- [ ] `ruff check src/ tests/` passes with no errors
+- [ ] `pytest tests/` passes locally
+- [ ] Documentation updated (if applicable)

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

@@ -0,0 +1,110 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: set up python
+        run: uv python install 3.13
+
+      - name: install dependencies
+        run: uv sync --extra dev --python 3.13
+        env:
+          UV_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
+
+      - name: ruff check
+        run: uv run ruff check src/ tests/
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: set up python
+        run: uv python install 3.13
+
+      - name: install dependencies
+        run: uv sync --extra dev --python 3.13
+        env:
+          UV_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
+
+      - name: bandit security scan
+        run: uv run bandit -r src/synapto/ -c pyproject.toml
+
+      - name: pip-audit dependency scan
+        run: uv run pip-audit
+
+  test:
+    runs-on: ubuntu-latest
+    needs: [lint, security]
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: synapto
+          POSTGRES_PASSWORD: synapto
+          POSTGRES_DB: synapto
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U synapto"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 5
+
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: set up python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: install dependencies (cpu-only torch for ci)
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+        env:
+          UV_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
+
+      - name: create pgvector extension
+        run: PGPASSWORD=synapto psql -h localhost -U synapto -d synapto -c "CREATE EXTENSION IF NOT EXISTS vector; CREATE EXTENSION IF NOT EXISTS pg_trgm;"
+
+      - name: test
+        env:
+          SYNAPTO_PG_DSN: postgresql://synapto:synapto@localhost:5432/synapto
+          SYNAPTO_REDIS_URL: redis://localhost:6379/1
+        run: uv run pytest tests/ -v --cov=synapto --cov-report=term-missing

synapto-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,140 @@
+name: release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump_type:
+        description: "version bump type (use 'current' to publish without bumping)"
+        required: true
+        type: choice
+        options:
+          - current
+          - patch
+          - minor
+          - major
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: release
+
+    steps:
+      - name: check admin permission
+        uses: actions-cool/check-user-permission@v2
+        id: check
+        with:
+          require: admin
+          username: ${{ github.triggering_actor }}
+
+      - name: abort if not admin
+        if: steps.check.outputs.require-result != 'true'
+        run: |
+          echo "error: only repo admins can create releases"
+          exit 1
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: set up python
+        run: uv python install 3.13
+
+      - name: install build tools
+        run: uv sync --extra dev --python 3.13
+
+      - name: bump version
+        id: bump
+        run: |
+          uv run python - <<'PYEOF'
+          import tomli, tomli_w, re, os
+
+          bump_type = "${{ inputs.bump_type }}"
+
+          with open("pyproject.toml", "rb") as f:
+              data = tomli.load(f)
+
+          current = data["project"]["version"]
+
+          if bump_type == "current":
+              new_version = current
+          else:
+              major, minor, patch = map(int, current.split("."))
+              if bump_type == "major":
+                  major, minor, patch = major + 1, 0, 0
+              elif bump_type == "minor":
+                  minor, patch = minor + 1, 0
+              else:
+                  patch += 1
+              new_version = f"{major}.{minor}.{patch}"
+
+              # update pyproject.toml
+              data["project"]["version"] = new_version
+              with open("pyproject.toml", "wb") as f:
+                  tomli_w.dump(data, f)
+
+              # update __init__.py
+              init_path = "src/synapto/__init__.py"
+              with open(init_path) as f:
+                  content = f.read()
+              content = re.sub(r'__version__ = "[^"]+"', f'__version__ = "{new_version}"', content)
+              with open(init_path, "w") as f:
+                  f.write(content)
+
+          with open(os.environ["GITHUB_OUTPUT"], "a") as f:
+              f.write(f"version={new_version}\n")
+              f.write(f"previous={current}\n")
+
+          print(f"bumped {current} -> {new_version}")
+          PYEOF
+
+      - name: build package
+        run: uv run python -m build
+
+      - name: commit version bump
+        if: inputs.bump_type != 'current'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml src/synapto/__init__.py
+          git commit -m "chore(synapto): bump version to ${{ steps.bump.outputs.version }}"
+          git push origin main
+
+      - name: create tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag "v${{ steps.bump.outputs.version }}"
+          git push origin "v${{ steps.bump.outputs.version }}"
+
+      - name: publish to pypi
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: create github release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: "v${{ steps.bump.outputs.version }}"
+          name: "v${{ steps.bump.outputs.version }}"
+          body: |
+            ## what's changed
+
+            see [CHANGELOG.md](https://github.com/ramonlimaramos/synapto/blob/main/CHANGELOG.md) for details.
+
+            ### install / upgrade
+
+            ```bash
+            pip install synapto==${{ steps.bump.outputs.version }}
+            ```
+
+            or with auto-updates (recommended):
+            ```json
+            { "command": "uvx", "args": ["synapto", "serve"] }
+            ```
+          files: dist/*

synapto-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+*.whl
+.venv/
+venv/
+env/
+.env
+.env.*
+!.env.example
+*.log
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+tmp/

synapto-0.1.0/.tool-versions

@@ -0,0 +1,2 @@
+python 3.13.1
+uv 0.8.24

synapto-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to Synapto will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-04-13
+
+### Added
+
+- **MCP server** with 10 tools: remember, recall, relate, forget, trust_feedback, find_contradictions, graph_query, list_entities, memory_stats, maintain
+- **3-way hybrid search** combining vector similarity (pgvector HNSW), full-text (tsvector + BM25), and HRR compositional algebra via Reciprocal Rank Fusion
+- **holographic reduced representations (HRR)** for compositional memory queries — probe, reason, and contradict operations that no vector database can do
+- **knowledge graph** with automatic entity extraction, directed relations, and N-hop recursive CTE traversal
+- **time-based decay** with 4 depth layers: core (forever), stable (~6 months), working (~1 week), ephemeral (~6 hours)
+- **trust scoring** with asymmetric feedback: helpful +0.05, unhelpful -0.10 for self-cleaning memory
+- **memory banks** using HRR bundled superpositions for O(1) category-level queries
+- **repository pattern** isolating all SQL into dedicated repository classes — zero raw SQL in business logic
+- **CLI** with commands: serve, init, search, stats, doctor, migrate (up/down/status), export, import
+- **interactive init** (`synapto init --interactive`) with MCP client auto-detection and uvx config
+- **multi-tenant isolation** via tenant scoping on all tables
+- **versioned SQL migrations** with up/down support and checksum validation
+- **embedding providers**: sentence-transformers (CPU default) and OpenAI
+- **CI pipeline** with lint (ruff), security (bandit), dependency audit (pip-audit), and tests across Python 3.11/3.12/3.13
+- **documentation** for Claude Code, Cursor, LangGraph, Agno integration
+- **docker compose** setup for quick start
+- **uvx support** as recommended installation method for automatic updates
+
+### Security
+
+- all SQL queries use parameterized placeholders (no string interpolation)
+- bandit static analysis integrated in CI
+- pip-audit dependency scanning in CI

synapto-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,111 @@
+# Contributing to Synapto
+
+Thanks for your interest in contributing to Synapto! This guide covers everything you need to get started.
+
+## Prerequisites
+
+- Python 3.11+
+- PostgreSQL 14+ with [pgvector](https://github.com/pgvector/pgvector)
+- Redis 7+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+Or just use Docker:
+
+```bash
+make docker-up    # starts postgres + redis + synapto
+```
+
+## Development Setup
+
+```bash
+git clone https://github.com/ramonlimaramos/synapto.git
+cd synapto
+
+# install with dev dependencies
+uv sync --extra dev
+# or: pip install -e ".[dev]"
+
+# initialize the database
+uv run synapto init
+```
+
+## Running Tests
+
+```bash
+# full suite
+uv run pytest tests/ -v
+
+# with coverage
+uv run pytest tests/ -v --cov=synapto --cov-report=term-missing
+
+# specific file
+uv run pytest tests/unit/test_hrr.py -v
+```
+
+Tests require a running PostgreSQL (with pgvector) and Redis instance. Connection strings are read from environment variables:
+
+| Variable | Default |
+|----------|---------|
+| `SYNAPTO_PG_DSN` | `postgresql://localhost/synapto` |
+| `SYNAPTO_REDIS_URL` | `redis://localhost:6379/1` |
+
+## Linting
+
+```bash
+uv run ruff check src/ tests/       # check code style
+uv run ruff format --check src/ tests/  # check formatting
+```
+
+We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+- Line length: 120 characters
+- Target: Python 3.11+
+- Rules: E, F, I, N, W, UP
+
+## Code Style
+
+- No ORM — raw SQL only (psycopg3)
+- Type hints on all public functions
+- Tests mirror the `src/` directory structure under `tests/unit/`
+
+## Commit Format
+
+All commit messages must be **lowercase** with a scoped prefix:
+
+```
+feat(synapto): add new embedding provider
+fix(synapto): handle empty query in hybrid search
+docs(synapto): update quickstart guide
+test(synapto): add graph traversal edge cases
+chore(synapto): bump dependency versions
+```
+
+## Submitting Pull Requests
+
+1. Fork the repository and create a branch from `main`
+2. Make your changes, including tests for new functionality
+3. Run `ruff check` and `pytest` to verify everything passes
+4. Commit with the format described above
+5. Open a PR against `main` with a clear description of what and why
+
+### PR Requirements
+
+- All CI checks must pass (lint + tests on Python 3.11/3.12/3.13)
+- At least one maintainer approval is required
+- Keep PRs focused — one feature or fix per PR
+
+### PR Checklist
+
+- [ ] Tests pass (`uv run pytest tests/`)
+- [ ] Lint passes (`uv run ruff check src/ tests/`)
+- [ ] New features include tests
+- [ ] Commit messages follow the format above
+- [ ] No new dependencies added without discussion
+
+## Releases
+
+Releases are published to PyPI and are **admin-only**. They are triggered manually via the GitHub Actions release workflow (`workflow_dispatch`). Contributors do not need to worry about versioning or publishing — maintainers handle this.
+
+## Questions?
+
+Open an [issue](https://github.com/ramonlimaramos/synapto/issues) or start a discussion on the repository.

synapto-0.1.0/Dockerfile

@@ -0,0 +1,38 @@
+# stage 1: builder
+FROM python:3.13-slim AS builder
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY src/ src/
+
+RUN pip install --no-cache-dir build && \
+    python -m build --wheel --outdir /app/dist
+
+# stage 2: runtime
+FROM python:3.13-slim
+
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends libpq5 && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/dist/*.whl /tmp/
+
+RUN pip install --no-cache-dir /tmp/*.whl && \
+    rm -f /tmp/*.whl
+
+# pre-download the default embedding model so first run is fast
+RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('multi-qa-MiniLM-L6-cos-v1')"
+
+COPY .env.example /app/.env.example
+
+ENV SYNAPTO_PG_DSN=postgresql://synapto:synapto@postgres:5432/synapto
+ENV SYNAPTO_REDIS_URL=redis://redis:6379/0
+
+# optional SSE transport
+EXPOSE 8080
+
+ENTRYPOINT ["synapto"]
+CMD ["serve"]

synapto-0.1.0/LICENSE

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

synapto-0.1.0/Makefile

@@ -0,0 +1,47 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help install dev test lint format security audit serve init doctor docker-up docker-down clean
+
+help: ## show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install: ## install synapto
+	uv sync
+
+dev: ## install with dev extras (tests, linting)
+	uv sync --extra dev
+
+test: ## run tests with pytest
+	uv run pytest tests/ -v
+
+lint: ## run ruff linter
+	uv run ruff check src/ tests/
+
+format: ## format code with ruff
+	uv run ruff format src/ tests/
+
+security: ## run bandit security scan
+	uv run bandit -r src/synapto/ -c pyproject.toml
+
+audit: ## audit dependencies for known vulnerabilities
+	uv run pip-audit
+
+serve: ## start the mcp server (stdio)
+	uv run synapto serve
+
+init: ## initialize database and config
+	uv run synapto init
+
+doctor: ## check system health
+	uv run synapto doctor
+
+docker-up: ## start all services with docker compose
+	docker compose up -d
+
+docker-down: ## stop all docker compose services
+	docker compose down
+
+clean: ## remove build artifacts and caches
+	rm -rf dist/ build/ *.egg-info/ .pytest_cache/ .ruff_cache/ htmlcov/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true