synaptic-state 0.1.0__tar.gz

synaptic_state-0.1.0/LICENSE

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

synaptic_state-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: synaptic-state
+Version: 0.1.0
+Summary: Verifiable State Plane for Autonomous Agents
+Author: SynapticAI Team
+License: MIT
+Keywords: ai-agent-memory,context-management,belief-revision,state-plane,agm,mcp-server,verification,context-budget,neuro-symbolic
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn>=0.27; extra == "server"
+Dynamic: license-file
+
+# 🧠⚡ SynapticAI
+
+**Semantic Multi-Layer Memory System for AI Agents**
+
+SynapticAI gives AI agents a unified memory architecture with semantic search, cross-layer bridging, and master index patterns — so your agent can actually *remember* and *connect the dots*.
+
+## The Problem
+
+AI agents typically have 4-5 separate memory systems:
+- Short-term injected memory (system prompt)
+- Vector database entries (semantic search)
+- Procedural skills (installation guides, workflows)
+- Session transcripts (conversation history)
+- Config files (tokens, env vars, auth)
+
+**None of them talk to each other.** You have to query each one separately.
+
+## The Solution
+
+SynapticAI connects them all with:
+
+1. **Master Index Pattern** — One authoritative entry per topic
+2. **Semantic Search First** — `fabric_recall` finds relevant info across all layers
+3. **Cross-Layer References** — Entries link to each other (`tags`, `session_id`, source)
+4. **Search Flow Priority** — Single query → ranked results from all layers
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│              fabric_recall "query"          │
+│         (semantic search — first stop)       │
+├─────────────┬───────────┬─────────┬─────────┤
+│  Memory     │  Fabric   │ Session │ Skills  │
+│  (prefs)    │  (notes,  │ (history│ (procs) │
+│  injected   │  decisions│  + LLM  │ + guide │
+│  per-turn)  │  + outcomes) │ sum)  │  lines  │
+└─────────────┴───────────┴─────────┴─────────┘
+         │           │           │
+         └───────────┼───────────┘
+                     ▼
+            Cross-Layer Index
+         (tags, session_id, refs)
+```
+
+## Search Flow
+
+```
+1. fabric_recall "query"      → semantic search (priority 1)
+2. fabric_search "keyword"    → exact keyword match
+3. session_search "query"     → historical conversations
+4. skills                     → procedural how-tos
+5. memory                     → user preferences (always injected)
+```
+
+## Master Index Structure
+
+Each master index is a single `fabric_write` entry tagged `master-index`:
+
+```markdown
+# Master Index — Topic Name
+
+## Current Status
+## Components
+## Auth & Config
+## Related Skills
+## Decisions Made
+## Cross-References → other master entries
+```
+
+## Installation
+
+```bash
+# For Hermes Agent users:
+# 1. Clone this repo
+# 2. Run the setup script
+./scripts/setup.sh
+
+# The script creates:
+# - Master index templates in ~/fabric/
+# - unified-search skill in ~/.hermes/skills/
+# - Memory bridge entries
+```
+
+## Usage
+
+Once installed, any agent can retrieve cross-layer memory with:
+
+```
+fabric_recall "any topic"    → ranked semantic results
+fabric_remember "decision"   → log important decisions
+fabric_link "entry_id"       → cross-reference entries
+```
+
+## Why It Works
+
+- **Lightweight** — No new infrastructure, just patterns on existing tools
+- **Agent-native** — Designed for AI agent memory, not human note-taking
+- **Extensible** — Works with fabric, session_search, skills, any config store
+- **Search-first** — Single query replaces 5 separate lookups
+
+## License
+
+MIT
+
+## Author
+
+Atakan Elik (@atakanelik34)

synaptic_state-0.1.0/README.md

@@ -0,0 +1,108 @@
+# 🧠⚡ SynapticAI
+
+**Semantic Multi-Layer Memory System for AI Agents**
+
+SynapticAI gives AI agents a unified memory architecture with semantic search, cross-layer bridging, and master index patterns — so your agent can actually *remember* and *connect the dots*.
+
+## The Problem
+
+AI agents typically have 4-5 separate memory systems:
+- Short-term injected memory (system prompt)
+- Vector database entries (semantic search)
+- Procedural skills (installation guides, workflows)
+- Session transcripts (conversation history)
+- Config files (tokens, env vars, auth)
+
+**None of them talk to each other.** You have to query each one separately.
+
+## The Solution
+
+SynapticAI connects them all with:
+
+1. **Master Index Pattern** — One authoritative entry per topic
+2. **Semantic Search First** — `fabric_recall` finds relevant info across all layers
+3. **Cross-Layer References** — Entries link to each other (`tags`, `session_id`, source)
+4. **Search Flow Priority** — Single query → ranked results from all layers
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│              fabric_recall "query"          │
+│         (semantic search — first stop)       │
+├─────────────┬───────────┬─────────┬─────────┤
+│  Memory     │  Fabric   │ Session │ Skills  │
+│  (prefs)    │  (notes,  │ (history│ (procs) │
+│  injected   │  decisions│  + LLM  │ + guide │
+│  per-turn)  │  + outcomes) │ sum)  │  lines  │
+└─────────────┴───────────┴─────────┴─────────┘
+         │           │           │
+         └───────────┼───────────┘
+                     ▼
+            Cross-Layer Index
+         (tags, session_id, refs)
+```
+
+## Search Flow
+
+```
+1. fabric_recall "query"      → semantic search (priority 1)
+2. fabric_search "keyword"    → exact keyword match
+3. session_search "query"     → historical conversations
+4. skills                     → procedural how-tos
+5. memory                     → user preferences (always injected)
+```
+
+## Master Index Structure
+
+Each master index is a single `fabric_write` entry tagged `master-index`:
+
+```markdown
+# Master Index — Topic Name
+
+## Current Status
+## Components
+## Auth & Config
+## Related Skills
+## Decisions Made
+## Cross-References → other master entries
+```
+
+## Installation
+
+```bash
+# For Hermes Agent users:
+# 1. Clone this repo
+# 2. Run the setup script
+./scripts/setup.sh
+
+# The script creates:
+# - Master index templates in ~/fabric/
+# - unified-search skill in ~/.hermes/skills/
+# - Memory bridge entries
+```
+
+## Usage
+
+Once installed, any agent can retrieve cross-layer memory with:
+
+```
+fabric_recall "any topic"    → ranked semantic results
+fabric_remember "decision"   → log important decisions
+fabric_link "entry_id"       → cross-reference entries
+```
+
+## Why It Works
+
+- **Lightweight** — No new infrastructure, just patterns on existing tools
+- **Agent-native** — Designed for AI agent memory, not human note-taking
+- **Extensible** — Works with fabric, session_search, skills, any config store
+- **Search-first** — Single query replaces 5 separate lookups
+
+## License
+
+MIT
+
+## Author
+
+Atakan Elik (@atakanelik34)

synaptic_state-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "synaptic-state"
+version = "0.1.0"
+description = "Verifiable State Plane for Autonomous Agents"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "SynapticAI Team"}]
+requires-python = ">=3.9"
+keywords = [
+    "ai-agent-memory",
+    "context-management",
+    "belief-revision",
+    "state-plane",
+    "agm",
+    "mcp-server",
+    "verification",
+    "context-budget",
+    "neuro-symbolic",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "mcp>=1.0.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "pytest-asyncio>=0.21",
+    "mypy>=1.0",
+    "ruff>=0.1",
+]
+server = [
+    "fastapi>=0.110",
+    "uvicorn>=0.27",
+]
+
+[project.scripts]
+synaptic = "synaptic_state.cli.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100

synaptic_state-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

synaptic_state-0.1.0/src/synaptic_state/__init__.py

@@ -0,0 +1,28 @@
+"""
+SynapticAI: Verifiable State Plane for Autonomous Agents
+
+Remember less. Stay correct longer.
+Neuro-Symbolic Memory That Learns What to Forget.
+"""
+
+__version__ = "0.1.0"
+__author__ = "SynapticAI Team"
+__license__ = "MIT"
+
+from synaptic_state.core.stateplane import StatePlane
+from synaptic_state.core.agm import AGMEngine, BeliefState
+from synaptic_state.core.verification import VerificationGate, VerificationResult
+from synaptic_state.adaptive.forgetting import LearnableForgetting
+from synaptic_state.retrieval.hybrid import HybridRetriever
+from synaptic_state.adaptive.budget import ContextBudgetRL
+
+__all__ = [
+    "StatePlane",
+    "AGMEngine",
+    "BeliefState", 
+    "VerificationGate",
+    "VerificationResult",
+    "LearnableForgetting",
+    "HybridRetriever",
+    "ContextBudgetRL",
+]

synaptic_state-0.1.0/src/synaptic_state/adaptive/__init__.py

@@ -0,0 +1,4 @@
+"""Adaptive layer: Budget Optimization and Learnable Forgetting."""
+from synaptic_state.adaptive.budget import ContextBudgetRL
+from synaptic_state.adaptive.forgetting import LearnableForgetting
+__all__ = ["ContextBudgetRL", "LearnableForgetting"]

synaptic_state-0.1.0/src/synaptic_state/adaptive/budget.py

@@ -0,0 +1,186 @@
+"""
+ContextBudget RL: Adaptive Context Budget Allocation
+
+Based on ContextBudget paper (arXiv:2604.01664):
+- Formulates context management as a sequential decision problem
+- Learns optimal compression strategies under varying budgets
+
+For MVP: Heuristic-based allocation (Phase 2: actual RL)
+"""
+
+from __future__ import annotations
+
+import time
+import logging
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class ContextBudgetRL:
+    """
+    Adaptive context budget optimizer.
+    
+    Allocates token budget across memory types based on:
+    1. Task type (coding, analysis, conversation, etc.)
+    2. History of what was most useful
+    3. Current context constraints
+    
+    MVP: Rule-based allocation with learning hooks.
+    Phase 2: Actual RL-trained policy network.
+    """
+    
+    # Default allocation percentages by strategy
+    ALLOCATION_PROFILES = {
+        "greedy": {
+            "episodic": 0.4,
+            "procedural": 0.2,
+            "semantic": 0.25,
+            "symbolic": 0.15,
+        },
+        "rl_optimized": {
+            "episodic": 0.3,
+            "procedural": 0.3,
+            "semantic": 0.25,
+            "symbolic": 0.15,
+        },
+        "symbolic_heavy": {
+            "episodic": 0.15,
+            "procedural": 0.2,
+            "semantic": 0.3,
+            "symbolic": 0.35,
+        },
+        "conversation": {
+            "episodic": 0.5,
+            "procedural": 0.1,
+            "semantic": 0.3,
+            "symbolic": 0.1,
+        },
+    }
+    
+    def __init__(
+        self,
+        default_budget: int = 2048,
+        max_budget: int = 8192,
+        learning_rate: float = 0.01,
+    ):
+        self.default_budget = default_budget
+        self.max_budget = max_budget
+        self.learning_rate = learning_rate
+        
+        # Learning state (for Phase 2 RL)
+        self._task_history: list = []
+        self._allocation_history: list = []
+        self._feedback_scores: list = []  # 0-1 scores post-task
+    
+    def allocate_budget(
+        self,
+        requested_budget: Optional[int] = None,
+        strategy: str = "rl_optimized",
+        task_type: str = "generic",
+        available_types: Optional[Dict[str, int]] = None,
+    ) -> Dict[str, int]:
+        """
+        Allocate token budget across memory types.
+        
+        Returns: {"episodic": N, "procedural": N, "semantic": N, "symbolic": N}
+        """
+        budget = min(
+            requested_budget or self.default_budget,
+            self.max_budget,
+        )
+        
+        profile = self.ALLOCATION_PROFILES.get(strategy, self.ALLOCATION_PROFILES["rl_optimized"])
+        
+        # Apply task-type adjustments
+        adjusted = self._adjust_for_task_type(profile, task_type)
+        
+        # Normalize
+        total = sum(adjusted.values())
+        if total > 0:
+            allocation = {
+                k: int(budget * v / total)
+                for k, v in adjusted.items()
+            }
+        else:
+            allocation = {k: budget // len(adjusted) for k in adjusted}
+        
+        # Log for learning
+        self._allocation_history.append({
+            "timestamp": time.time(),
+            "budget": budget,
+            "strategy": strategy,
+            "task_type": task_type,
+            "allocation": allocation,
+        })
+        
+        # Apply available constraints
+        if available_types:
+            for mem_type, available_count in available_types.items():
+                if mem_type in allocation and available_count == 0:
+                    allocation[mem_type] = 0
+        
+        return allocation
+    
+    def record_feedback(self, task_type: str, score: float, allocation: Dict[str, int]) -> None:
+        """
+        Record task feedback for future learning.
+        
+        score: 0.0 (bad allocation) to 1.0 (perfect allocation)
+        """
+        self._feedback_scores.append({
+            "timestamp": time.time(),
+            "task_type": task_type,
+            "score": score,
+            "allocation": allocation,
+        })
+    
+    def _adjust_for_task_type(self, profile: Dict[str, float], task_type: str) -> Dict[str, float]:
+        """Adjust allocation ratios based on task type."""
+        adjusted = dict(profile)
+        
+        adjustments = {
+            "coding": {"procedural": 0.15, "symbolic": 0.1, "episodic": -0.1, "semantic": -0.05},
+            "debug": {"episodic": 0.15, "procedural": 0.1, "symbolic": 0.0, "semantic": 0.0},
+            "analysis": {"semantic": 0.15, "episodic": 0.05, "procedural": -0.05, "symbolic": -0.05},
+            "conversation": {"episodic": 0.2, "semantic": 0.1, "procedural": -0.15, "symbolic": -0.05},
+        }
+        
+        task_adjust = adjustments.get(task_type, {})
+        for mem_type, delta in task_adjust.items():
+            if mem_type in adjusted:
+                adjusted[mem_type] = max(0.05, adjusted[mem_type] + delta)
+        
+        return adjusted
+    
+    def get_optimal_strategy(self, task_type: str = "generic") -> str:
+        """
+        Suggest optimal strategy based on historical feedback.
+        
+        For Phase 2: this will use learned RL policy.
+        For MVP: simple heuristic.
+        """
+        if not self._feedback_scores:
+            return "rl_optimized"
+        
+        # Find highest-scoring strategy for this task type
+        task_feedback = [f for f in self._feedback_scores if f["task_type"] == task_type]
+        if not task_feedback:
+            return "rl_optimized"
+        
+        # Simple averaging
+        avg_scores: Dict[str, float] = {}
+        for fb in task_feedback:
+            strategy = fb.get("allocation", {}).get("_strategy", "rl_optimized")
+            if strategy not in avg_scores:
+                avg_scores[strategy] = []
+            avg_scores[strategy].append(fb["score"])
+        
+        if not avg_scores:
+            return "rl_optimized"
+        
+        best_strategy = max(
+            avg_scores.items(),
+            key=lambda x: sum(x[1]) / len(x[1])
+        )
+        return best_strategy[0]