# Summon

Self-evolving knowledge graph for AI agents — persistent memory that gets smarter with every interaction.

**pip install, 2 lines of config, your agent remembers everything.**

[![PyPI](https://img.shields.io/pypi/v/summon-mcp)](https://pypi.org/project/summon-mcp/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)

## Why Summon?

AI agents forget everything between sessions. Vector DBs remember but don't understand relationships. Summon gives agents **structured, evolving memory** that:

- **Self-evolves** — frequently used knowledge strengthens; stale knowledge decays
- **Connects the dots** — automatic relationship detection between memories (graph edges)
- **Detects contradictions** — flags conflicting memories before they poison your agent's output
- **Learns from usage** — recall feedback loop tunes retention automatically

## Quick Start

### Install

```bash
pip install summon-mcp
```

### Use as a Python SDK

```python
from summon import Summon

sb = Summon()

# Remember
sb.remember("The production database is PostgreSQL 15 on AWS RDS", tags=["db", "prod"])
sb.remember("API rate limit is 1000 req/min per user", tags=["api", "limits"])

# Recall
results = sb.recall("what database do we use?")
for r in results:
    print(f"[{r.confidence:.0%}] {r.content}")

# Link memories
sb.link(source_id=1, target_id=2, relationship="depends_on")

# Traverse the knowledge graph
graph = sb.traverse(memory_id=1, hops=2)
```

### Use with Claude Code

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "summon": {
      "command": "python",
      "args": ["-m", "summon"],
      "env": {
        "SUPERBRAIN_DB_PATH": "~/.summon/memory.db"
      }
    }
  }
}
```

That's it. Claude Code now has persistent memory.

## Features

### 30 MCP Tools

| Category | Tools |
|----------|-------|
| **Memory CRUD** | `remember`, `recall`, `forget`, `reinforce` |
| **Knowledge Graph** | `link`, `traverse`, `find_similar`, `associative_recall` |
| **Evolution** | `decay_maintenance`, `auto_tune`, `dream`, `evolve` |
| **Analysis** | `detect_contradictions`, `synthesize`, `compress`, `clusters` |
| **Export** | `export_cards`, `export_knowledge`, `export_vectors`, `mermaid` |
| **Meta** | `health`, `status`, `changelog`, `diff`, `weekly_report` |

### Self-Evolution Engine

- **Edge heating** — frequently traversed paths strengthen; cold ones decay
- **SM-2 spaced repetition** — memories reviewed on optimal schedules (like Anki)
- **Auto-tune decay** — retention thresholds adjust based on actual usage patterns
- **Recall feedback loop** — tracks which searches were useful, learns from it
- **Episodic consolidation** — old episodes auto-summarize into permanent facts

### Storage

- **SQLite** — zero-config local storage, perfect for single-user
- **Pluggable backends** — swap in PostgreSQL, ChromaDB, or custom stores
- **BYOM embeddings** — bring your own model (OpenAI, DeepSeek, Ollama, local sentence-transformers)

## SDK Reference

```python
from summon import Summon, Memory, Edge

sb = Summon()                          # local SQLite (default)
sb = Summon(base_url="...", api_key="...")  # remote API

# Write
mem = sb.remember("fact", tags=["tag"], confidence=0.8)

# Read
mem = sb.get(memory_id)
results = sb.recall("query", mode="hybrid", limit=10)

# Graph
edge_id = sb.link(source=1, target=2, relationship="depends_on")
graph = sb.traverse(memory_id=1, hops=2)

# Manage
sb.reinforce(memory_id)
sb.forget(memory_id, mode="decay")   # or mode="delete"
sb.stats()                           # database statistics
sb.strongest()                       # top memories
sb.weakest()                         # at-risk memories
```

## Community

- **License**: Apache 2.0 — free for commercial use
- **Python**: 3.9+
- **Status**: v0.4.0 Beta — stable for personal use, API may evolve before 1.0

## Roadmap

- [ ] Cloud sync ($5/mo)
- [ ] Multi-tenant SaaS
- [ ] LangChain / CrewAI integrations
- [ ] Web dashboard
- [ ] v1.0 stable API

---

Built for developers who want their AI agents to stop forgetting.