synap 0.1.0__tar.gz

synap-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,56 @@
+name: Bug Report
+description: Report something that isn't working correctly
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Minimal code or steps to reproduce the issue.
+      render: python
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Engram version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: backend
+    attributes:
+      label: Storage backend
+      options:
+        - In-memory (default)
+        - KuzuBackend
+        - SQLiteBackend
+        - Other / N/A
+    validations:
+      required: true

synap-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: Feature Request
+description: Suggest an idea or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or motivation
+      description: What problem does this solve, or what would it enable?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How would you like this to work? Code sketches welcome.
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you've thought about.
+    validations:
+      required: false

synap-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## What does this PR do?
+
+<!-- Brief description of the change -->
+
+## Why?
+
+<!-- Motivation: what problem does this solve, or what issue does it close? -->
+
+## Checklist
+
+- [ ] Tests added or updated
+- [ ] Documentation updated (if changing public API)
+- [ ] `pytest` passes locally

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

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    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: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest

synap-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

synap-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.db
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+.env
+.env.local

synap-0.1.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# 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).
+
+## [Unreleased]
+
+### Changed
+
+- **Breaking:** `EpisodicMemory.recall()` now reconstructs episodes from graph traversal instead of an in-memory dict — episodic memory now works correctly across process restarts with persistent storage
+- **Breaking:** `EpisodicMemory.find_patterns()` is now async (`await ep.find_patterns(...)`)
+- **Breaking:** `EpisodicMemory.episode_count` property replaced with async method `episode_count()` (`await ep.episode_count()`)
+- **Breaking:** `CognitiveMemory.evaluate()` is now async (`await memory.evaluate()`)
+- **Breaking:** `ProceduralMemory.match()` now reconstructs procedures from graph — procedures survive process restarts with persistent storage
+- **Breaking:** `ProceduralMemory.get_procedure()` and `list_procedures()` are now async
+- **Breaking:** `StorageBackend` protocol now requires `node_count()` and `edge_count()` methods
+- `EpisodicMemory.record()` now stores structured metadata (episode content, tool calls, correction) on graph nodes for round-trip reconstruction
+- `ProceduralMemory.register()` now stores all Procedure fields in node metadata for reconstruction
+- `ConsolidationEngine.run_periodic()` queries the graph instead of accessing internal episodic state
+- `PersistentGraph.node_count()` and `edge_count()` delegate to backend-native counts instead of loading all rows
+
+### Fixed
+
+- **Procedural consolidation now actually amends procedures** — `_consolidate_to_procedural` generates a new schema field via LLM, registers a new Procedure version with `supersedes` edge, so `prepare_call()` returns the amended schema
+- **Corrective hints now work** — `_corrective_hints()` reads correction text from episode outcome nodes; hints are injected into schema descriptions of fields with prerequisites (decision fields)
+- `CognitiveMemory.evaluate()` now populates `cold_spots` (task types with ≤2 episodes) — previously always returned empty
+- Warning effectiveness tracking is now per-call, not cumulative across the session
+- **Split-graph guard** — `CognitiveMemory` raises `ValueError` if the domain adapter's graph differs from the graph passed to the constructor
+- Removed misleading `sqlite` optional dependency (`aiosqlite`) — `SQLiteBackend` uses stdlib `sqlite3`
+
+### Added
+
+- `EpisodicMemory._reconstruct_episode()` — rebuilds Episode from graph traversal (cue→content→outcome)
+- `EpisodicMemory.all_episodes()` — reconstructs all episodes from the graph
+- `ProceduralMemory._reconstruct_procedure()` — rebuilds Procedure from graph node metadata
+- `StorageBackend.node_count()` and `edge_count()` — efficient count queries for Kuzu and SQLite backends
+- Shared `_utils.cosine_similarity()` — deduplicated from graph, episodic, and sqlite modules
+
+## [0.1.0] - 2026-03-17
+
+### Added
+
+- Three-subsystem cognitive memory architecture: semantic, procedural, episodic
+- `CognitiveMemory` facade with `prepare_call`, `record_outcome`, `consolidate`
+- Pluggable `SemanticDomain` protocol for domain-specific knowledge types
+- Built-in `SemanticMemory` with embedding-based graph traversal
+- `ProceduralMemory` with output schema enforcement via field ordering
+- `EpisodicMemory` with cue-content-outcome subgraphs and pattern detection
+- `ToolCall` tracking for structured tool invocation recording
+- `ConsolidationEngine` for episodic-to-domain learning
+- `Bootstrap` helper for cold-start knowledge extraction
+- In-memory `MemoryGraph` with BFS traversal and cosine similarity
+- `KuzuBackend` with native Cypher traversal and vector search
+- `SQLiteBackend` with JSON blob storage and indexed queries
+- `PersistentGraph` async wrapper for storage backends
+- Async-first public API designed for framework integration

synap-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to Synap
+
+Thanks for your interest in contributing to Synap! This guide will help you get started.
+
+## Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/veeeceee/synap.git
+cd synap
+
+# Create a virtual environment and install dev dependencies
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Or with uv
+uv sync --extra dev
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+Tests use fake embedding and LLM providers (defined in `tests/conftest.py`), so no external services are needed.
+
+## Making Changes
+
+1. **Fork the repo** and create a branch from `main`
+2. **Write tests** for any new functionality
+3. **Run the test suite** to make sure nothing is broken
+4. **Keep your PR focused** — one concern per pull request
+5. **Update documentation** if you're changing public API
+
+## Code Style
+
+- Type hints on all public functions and methods
+- Docstrings on public classes and methods
+- Follow the existing patterns — protocols for extension points, dataclasses for data
+- Async-first: public API methods should be async
+
+## Architecture Notes
+
+Before diving in, read [docs/architecture.md](docs/architecture.md) to understand the three-subsystem design and why decisions were made.
+
+Key principles:
+- **Protocols over inheritance** — consumers implement `EmbeddingProvider`, `LLMProvider`, `SemanticDomain`, etc.
+- **Zero required dependencies** — core library has no runtime deps; backends are optional
+- **Graph is the integration layer** — all subsystems share one typed property graph
+
+## What to Work On
+
+- Check [open issues](../../issues) for bugs and feature requests
+- Issues labeled `good first issue` are a great starting point
+- If you want to work on something larger, open an issue first to discuss the approach
+
+## Pull Requests
+
+- Fill out the PR template
+- Ensure tests pass
+- Keep commits focused and well-described
+- Be open to feedback — code review is collaborative, not adversarial
+
+## Questions?
+
+Open a [discussion](../../discussions) or comment on the relevant issue.

synap-0.1.0/LICENSE

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

synap-0.1.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: synap
+Version: 0.1.0
+Summary: Cognitive memory architecture for LLM agents
+Project-URL: Homepage, https://github.com/veeeceee/synap
+Project-URL: Repository, https://github.com/veeeceee/synap
+Project-URL: Issues, https://github.com/veeeceee/synap/issues
+Project-URL: Changelog, https://github.com/veeeceee/synap/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: kuzu>=0.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: kuzu
+Requires-Dist: kuzu>=0.8.0; extra == 'kuzu'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0.0; extra == 'mcp'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.30.0; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# Synap
+
+[![CI](https://github.com/veeeceee/synap/actions/workflows/ci.yml/badge.svg)](https://github.com/veeeceee/synap/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/synap)](https://pypi.org/project/synap/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Cognitive memory architecture for LLM agents.
+
+Synap manages three types of memory — semantic, procedural, and episodic — backed by a shared typed property graph. It resolves the fundamental memory-vs-attention contradiction in transformer-based models: more context degrades reasoning quality. Instead of stuffing everything into the prompt, Synap uses structurally selective retrieval (similarity search finds entry points, then graph traversal returns connected subgraphs instead of flat ranked lists) and output-side enforcement (procedures become output schemas, not instructions).
+
+## How is this different?
+
+Most agent memory systems (Mem0, Letta, Zep, LangMem) treat memory as a retrieval problem — store text, find similar text, put it in the prompt. Synap takes a different position:
+
+- **Structural enforcement, not instructions.** Procedural memory produces output schemas where field ordering *is* the reasoning procedure. The model must generate evidence before conclusions — enforced by the schema, not by telling it to "think step by step."
+- **Graph traversal, not flat retrieval.** Semantic memory returns connected subgraphs where relationships are explicit. A query about "lumbar fusion requirements" traverses `requires` and `includes` edges, not just the top-K similar chunks.
+- **Self-amending procedures.** When the same failure pattern repeats, the consolidation engine generates a new schema field and registers an amended procedure version. The system structurally prevents the mistake from recurring.
+- **Precision over convenience.** Synap is a library, not a managed service. You own the agent loop, the LLM client, and the embedding provider. Memory operations are explicit and auditable.
+
+## Installation
+
+```bash
+pip install synap
+
+# With Kùzu for persistent graph storage (recommended)
+pip install synap[kuzu]
+
+# With uv
+uv add synap --extra kuzu
+```
+
+## Providers
+
+Synap needs two providers you implement — one for embeddings, one for LLM text generation. Here's a minimal example using OpenAI:
+
+```python
+import openai
+
+class OpenAIEmbedder:
+    def __init__(self, client: openai.AsyncOpenAI, model: str = "text-embedding-3-small"):
+        self.client = client
+        self.model = model
+
+    async def embed(self, text: str) -> list[float]:
+        response = await self.client.embeddings.create(input=text, model=self.model)
+        return response.data[0].embedding
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        response = await self.client.embeddings.create(input=texts, model=self.model)
+        return [item.embedding for item in response.data]
+
+
+class OpenAILLM:
+    def __init__(self, client: openai.AsyncOpenAI, model: str = "gpt-4o"):
+        self.client = client
+        self.model = model
+
+    async def generate(self, prompt: str, output_schema: dict | None = None) -> str:
+        response = await self.client.chat.completions.create(
+            model=self.model,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return response.choices[0].message.content
+```
+
+Any class matching the `EmbeddingProvider` and `LLMProvider` protocols works — no inheritance required. See [docs/architecture.md](docs/architecture.md#provider-model) for details.
+
+## Quick Start
+
+```python
+from synap import (
+    CognitiveMemory, CapacityHints, Procedure, EpisodeOutcome,
+    SemanticMemory, MemoryGraph,
+)
+
+# Create the graph and domain adapter
+graph = MemoryGraph()
+domain = SemanticMemory(graph=graph, embedding_provider=your_embedder)
+
+# You provide the embedding and LLM providers
+memory = CognitiveMemory(
+    domain=domain,
+    embedding_provider=your_embedder,
+    llm_provider=your_llm,
+    graph=graph,
+    capacity=CapacityHints(max_context_tokens=8192),
+)
+
+# Register a procedure — field ordering IS the enforcement
+await memory.procedural.register(Procedure(
+    task_type="diagnose_bug",
+    description="Diagnose a bug from error logs and code context",
+    schema={
+        "error_classification": {"type": "string"},
+        "root_cause": {"type": "string"},
+        "fix_proposal": {"type": "string"},
+    },
+    field_ordering=["error_classification", "root_cause", "fix_proposal"],
+    prerequisite_fields={"fix_proposal": ["error_classification", "root_cause"]},
+))
+
+# Seed knowledge
+await domain.store("Stripe webhook payloads vary by event type; always validate shape")
+
+# Prepare context for an LLM call
+ctx = await memory.prepare_call(
+    task_description="Diagnose TypeError in payment webhook handler"
+)
+# ctx.output_schema → enforces: classify error → find root cause → THEN propose fix
+# ctx.domain_context → relevant facts from the domain adapter
+# ctx.warnings → "Last time you misdiagnosed a similar TypeError..."
+
+# Record what happened (including tool calls if any)
+from synap import ToolCall
+
+await memory.record_outcome(
+    task_description="Diagnose TypeError in payment webhook handler",
+    input_data={"error": "Cannot read property 'amount' of undefined"},
+    output={"error_classification": "null reference", "root_cause": "...", "fix_proposal": "..."},
+    outcome=EpisodeOutcome.SUCCESS,
+    task_type="diagnose_bug",
+    tool_calls=[
+        ToolCall(
+            query="find webhook handler source",
+            server="code-search",
+            tool_name="search_files",
+            parameters={"pattern": "handleWebhook"},
+            result_summary="Found src/webhooks/stripe.ts:45",
+            success=True,
+        ),
+    ],
+)
+```
+
+## Domain Adapters
+
+Synap's semantic layer is pluggable via the `SemanticDomain` protocol. Every project brings its own knowledge types — contradictions and forces for geopolitical analysis, clinical policies for healthcare, code patterns for dev tools.
+
+```python
+from synap.protocols import SemanticDomain
+from synap.types import DomainResult, MemoryNode
+
+class MyDomain:
+    """Implements SemanticDomain — retrieves and absorbs domain knowledge."""
+
+    async def retrieve(self, task_description, task_type=None, metadata=None):
+        # Return domain knowledge relevant to this task
+        return [DomainResult(content="...", relevance=0.9, source_id="...")]
+
+    async def absorb(self, insights, source_episodes, metadata=None):
+        # Store consolidated insights in your domain's schema
+        return "domain_node_id"
+```
+
+`SemanticMemory` is the built-in generic implementation — text nodes with embeddings and graph traversal. Use it to get started, replace it when your domain needs custom types.
+
+## Persistence
+
+By default, the graph lives in memory. Pass a storage backend for persistence:
+
+```python
+from synap.backends.kuzu import KuzuBackend
+from synap.persistent_graph import PersistentGraph
+
+backend = KuzuBackend("./agent_memory", embedding_dim=768)
+graph = PersistentGraph(backend=backend)
+domain = SemanticMemory(graph=graph, embedding_provider=your_embedder)
+
+memory = CognitiveMemory(
+    domain=domain,
+    embedding_provider=your_embedder,
+    llm_provider=your_llm,
+    graph=graph,
+)
+```
+
+For multi-process deployments (web servers, worker pools), use the Postgres backend:
+
+```bash
+pip install synap[postgres]
+```
+
+```python
+import asyncpg
+from synap.backends.postgres import PostgresBackend
+from synap.persistent_graph import PersistentGraph
+
+pool = await asyncpg.create_pool("postgresql://localhost:5432/mydb")
+backend = PostgresBackend(pool, embedding_dim=768)
+await backend.init()  # Creates tables (idempotent)
+graph = PersistentGraph(backend=backend)
+```
+
+| Backend | Graph traversal | Vector search | Persistence | Concurrency |
+|---|---|---|---|---|
+| In-memory (default) | Python BFS | Python cosine | None | Single process |
+| `KuzuBackend` | Native Cypher | Native `array_cosine_similarity` | File-based | Single process |
+| `SQLiteBackend` | Python BFS | Python cosine | File-based | Single process |
+| `PostgresBackend` | Recursive CTE | pgvector `<=>` | Server-based | Multi-process safe |
+
+## Documentation
+
+- [Architecture & Concepts](docs/architecture.md) — How the three memory subsystems work and why
+- [API Reference](docs/api.md) — Complete interface documentation
+- [Bootstrap Guide](docs/bootstrap.md) — Cold start: seeding memory from existing data
+- [Examples](docs/examples.md) — Geopolitical analysis, healthcare, coding agents
+
+## How It Works
+
+**Semantic memory** is pluggable via the `SemanticDomain` protocol. The built-in `SemanticMemory` stores facts as a knowledge graph with retrieval via graph traversal. Projects with domain-specific types (contradictions, policies, etc.) implement the protocol directly.
+
+**Procedural memory** maps task types to output schemas where field ordering *is* the procedure. The model must generate intermediate reasoning before conclusions. Enforced structurally, not instructionally.
+
+**Episodic memory** records agent experiences as cue→content→outcome subgraphs. Failed episodes are boosted during retrieval (more learning signal). Over time, repeated patterns consolidate into domain knowledge or procedural amendments. Episodes can include structured **tool call tracking** — which MCP server, tool, parameters, and result — enabling consolidation to detect tool usage patterns (wrong tool selection, parameter malformation) and generate procedural amendments.
+
+All three operate on a shared typed property graph. Edges cross partitions — this is how consolidation links episodic experiences to domain facts without a separate join mechanism.
+
+## Async-First
+
+All public APIs are async. Synap is designed for integration with async frameworks (FastAPI, Sanic, etc.):
+
+```python
+# All operations are awaitable
+ctx = await memory.prepare_call("task description")
+episode_id = await memory.record_outcome(...)
+results = await memory.consolidate()
+stats = await memory.stats()
+```
+
+Storage backends stay synchronous (embedded DBs don't benefit from async). `PersistentGraph` bridges with `asyncio.to_thread`.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.