Syne 🧠

AI Agent Framework with Unlimited Memory

"I remember, therefore I am"

Named after Mnemosyne, the Greek goddess of memory and mother of the Muses.

Syne is a standalone, open-source AI agent framework built in Python. It features PostgreSQL-native memory with semantic search, an ability-based architecture for extensibility, and self-evolution capabilities where the agent can create new abilities for itself.

Why Syne?

Most AI assistants forget everything between sessions. They have no persistent memory, no learning, no growth. Syne is different:

• Unlimited memory — Semantic search over millions of memories using pgvector
• Anti-hallucination — 3-layer defense ensures only user-confirmed facts are stored
• Self-evolving — Syne can create new abilities for itself (with your permission)
• No config files — Everything lives in PostgreSQL. Change behavior through conversation, not YAML
• Near-zero cost — Chat via Google Gemini OAuth (free). Embedding via Ollama (local, $0) or Together AI (~$0.008/1M tokens)
• Interactive CLI — Code like Claude Code, but with persistent memory and tools

Cost

The table below shows the minimum cost setup using free OAuth providers. During syne init, you choose your own chat LLM and embedding provider — costs vary depending on your choice.

Minimum cost setup (Google Gemini + Ollama):

Other provider options available during install:

Costs depend entirely on which providers you choose. The free OAuth + Ollama combo above gives you a completely free setup.

Minimum Requirements

Quick Start

Installation

git clone https://github.com/riyogarta/syne.git
cd syne
bash install.sh

install.sh automatically installs all dependencies (python3-venv, pip, etc.), creates a virtual environment, installs Syne, and runs syne init.

What syne init Does

syne init is fully automated — no manual steps mid-install:

1. Choose AI provider — OAuth (free) or API key (paid)
2. Choose embedding provider — Ollama (free, local), Together AI, or OpenAI
3. Enter Telegram bot token — from @BotFather
4. Web search API key (optional) — Brave Search, free tier 2,000 queries/month. Can be added later via chat.
5. Start PostgreSQL — Docker container with pgvector, auto-install Docker if needed
6. Install Ollama (if selected) — Auto-install binary + pull qwen3-embedding model
7. Initialize database — Schema, identity, credentials saved to DB
8. Setup systemd service — Auto-start on boot, linger enabled

When init finishes, Syne is running.

Verify Installation

syne repair     # Diagnose: DB, OAuth, Telegram, abilities
syne status     # Quick status check

No Config Files — Just Talk

Most agent frameworks require editing SOUL.md, AGENTS.md, or CONFIG.yaml. Syne has none of that. Everything lives in PostgreSQL, and you change it through chat:

Fresh install comes with sensible defaults. Override anything through conversation — no SQL, no files.

Memory System

Three-Layer Anti-Hallucination

Only user-confirmed facts are stored. Never assistant suggestions.

User message
    │
    ├─ Layer 1: Quick Filter (no LLM call)
    │   └─ Skip: greetings, short messages, questions-only
    │
    ├─ Layer 2: LLM Evaluation
    │   └─ Is this worth remembering?
    │
    └─ Layer 3: Similarity Dedup
        └─ Does this already exist?

Conflict Resolution

When storing a new memory, similarity to existing memories determines the action:

Auto Capture vs Manual

⚠️ auto_capture = true adds extra LLM + embedding calls per message. On free-tier OAuth this exhausts rate limits faster.

Managing Your Memories

You:  What do you remember about my family?
Syne: [recalls relevant memories via semantic search]

You:  Remember: I'm allergic to shellfish.
Syne: Stored. ✅

You:  Forget that I like sushi.
Syne: Removed from memory. ✅

Via CLI: syne memory stats, syne memory search "query", syne memory add "info"

Embedding Providers

During syne init, you choose one of three embedding providers:

Ollama is auto-installed during syne init if selected — binary, server, and model are all set up automatically. If your system doesn't meet the minimum requirements (2 CPU, 2 GB RAM, 2 GB disk), the Ollama option is shown but blocked.

⚠️ Switching embedding providers deletes all stored memories. Different models produce incompatible vector spaces — there is no migration path. Use the /embedding command in Telegram to switch.

Ability System

Core Tools (19 — Always Available)

Bundled Abilities

Each ability requires its own API key. Just tell Syne in chat: "Set up image generation" — it will ask for the key and configure itself.

Managing Abilities

You:  Enable image generation
Syne: Done — image_gen enabled. ✅

You:  What abilities do I have?
Syne: ✅ image_gen, ✅ image_analysis, ❌ maps (disabled)

Self-Modification

Syne can create new abilities at runtime — no restart required:

Flow

User: "I wish you could check Bitcoin prices"
    │
    ├─ Syne writes syne/abilities/crypto_price.py
    ├─ Registers via update_ability (source='self_created')
    ├─ Ability is immediately available
    │
    └─ "Created 'crypto_price' ability. Try: what's BTC now?"

Safety Rules

Ability Interface

class Ability:
    name: str
    description: str
    version: str

    async def execute(self, params: dict, context: dict) -> dict: ...
    def get_schema(self) -> dict: ...

⚠️ Security Warning (exec)

The exec tool gives Syne shell access on the host system. This is powerful but dangerous:

• Owner-only — Only users with owner access level can trigger exec
• Timeout — Configurable per-session via session.max_tool_rounds (default: 100)
• Sub-agents — Inherit exec access but run in isolated sessions
• Your responsibility — Review what Syne executes, especially on production systems

Sub-agents

Syne can spawn isolated background agents for parallel tasks:

User: "Write full documentation for the project"
    │
    ├─ Syne spawns sub-agent (background)
    ├─ Main session continues chatting
    └─ Sub-agent completes → results delivered back

Sub-agents inherit abilities and memory access but run in isolated sessions. They cannot spawn other sub-agents.

Multi-User Access

Syne supports multiple users with different access levels:

The first user to message Syne automatically becomes owner.

Manage via conversation: "Make @alice family", "Remove @bob's access"

Configuration Reference

All configuration lives in the config table. Defaults below reflect the recommended setup from syne init (Google Gemini + Together AI). Change via conversation or SQL.

Provider Settings

Memory Settings

Session Settings

Sub-agent Settings

CLI Commands

# Setup & Running
syne init                  # Interactive setup (fully automated)
syne start                 # Start Telegram agent
syne start --debug         # Start with debug logging
syne cli                   # Interactive terminal chat (resumes by default)
syne cli --new             # Start fresh conversation (clear history)
syne cli --yolo            # Skip file write approvals (auto-yes)
syne cli --debug           # CLI with debug logging
syne status                # Show status
syne repair                # Diagnose and repair
syne restart               # Restart agent
syne stop                  # Stop agent

# Updates
syne update                # Update to latest release (skips if version unchanged)
syne updatedev             # Force pull + reinstall (ignores version check)

# Database
syne db init               # Initialize schema
syne db reset              # Reset database (destructive!)

# Identity
syne identity              # View identity
syne identity name "Syne"  # Set identity value
syne prompt                # Show system prompt

# Memory
syne memory stats          # Memory statistics
syne memory search "query" # Semantic search
syne memory add "info"     # Manually add memory

Interactive CLI Commands

CLI Features

• Per-directory sessions — each directory has its own conversation context, auto-resumed
• --new — start fresh conversation (clears history for this directory)
• Multiline input — Shift+Enter for new line, Enter to submit, paste preserved
• File write approval — Syne asks before writing files (yes / no / always). Skip with --yolo
• Tool activity indicator — spinner shows what Syne is doing (Thinking → Searching memory → Running command...)
• Ctrl+C — single tap cancels current request, double tap exits
• Auto-compaction — notifies when context is compacted

Telegram Commands

Architecture

+------------------------------------------------------------+
|                       SYNE AGENT                           |
|                                                            |
|  +------------------------------------------------------+  |
|  |                 CORE (Protected)                     |  |
|  |                                                      |  |
|  |  [Chat]  [Memory]  [Compaction]  [Channels]  [Sub]   |  |
|  |  (LLM)   (pgvec)    (context)   (TG + CLI)  agent   |  |
|  |                                                      |  |
|  |  Core Tools (19):                                    |  |
|  |  exec · memory · web · config · files · cron · voice  |  |
|  |  files · cron · reactions · voice                     |  |
|  +------------------------------------------------------+  |
|                                                            |
|  +------------------------------------------------------+  |
|  |              ABILITIES (Pluggable)                   |  |
|  |                                                      |  |
|  |  [image_gen]  [image_analysis]  [maps]  [custom...]  |  |
|  |                                                      |  |
|  |  Self-Created: Syne adds new abilities at runtime    |  |
|  +------------------------------------------------------+  |
|                                                            |
|  +------------------------------------------------------+  |
|  |              PostgreSQL + pgvector                   |  |
|  |  13 tables — all state in one database              |  |
|  |  memory · sessions · messages · config · abilities · |  |
|  |  groups · subagent_runs · capabilities ·             |  |
|  |  scheduled_tasks                                     |  |
|  +------------------------------------------------------+  |
+------------------------------------------------------------+

Database Schema

Tech Stack

Project Structure

syne/
├── syne/
│   ├── main.py              # Entry point
│   ├── agent.py             # Main agent coordinator
│   ├── boot.py              # System prompt builder
│   ├── config.py            # Settings loader
│   ├── conversation.py      # Session management
│   ├── context.py           # Context window management
│   ├── compaction.py        # Conversation summarization
│   ├── security.py          # Rule 700/760 enforcement
│   ├── cli.py               # CLI commands (init, start, repair, etc.)
│   ├── auth/
│   │   └── google_oauth.py  # Google CCA OAuth PKCE
│   ├── llm/
│   │   ├── provider.py      # Abstract LLM interface
│   │   ├── drivers.py       # Driver registry + model system
│   │   ├── google.py        # Gemini (OAuth)
│   │   ├── codex.py         # ChatGPT/Codex (OAuth)
│   │   ├── openai.py        # OpenAI-compatible (Groq, etc.)
│   │   ├── anthropic.py     # Claude (OAuth)
│   │   ├── together.py      # Together AI (embedding)
│   │   ├── ollama.py        # Ollama (local embedding)
│   │   └── hybrid.py        # Chat + Embed from different providers
│   ├── memory/
│   │   ├── engine.py        # Store, recall, dedup, conflict resolution
│   │   └── evaluator.py     # Auto-evaluate (3-layer filter)
│   ├── channels/
│   │   ├── telegram.py      # Telegram bot adapter
│   │   └── cli_channel.py   # Interactive CLI (REPL)
│   ├── tools/               # 19 core tools
│   ├── abilities/           # Bundled + self-created abilities
│   ├── scheduler.py         # Cron/scheduled task runner
│   └── db/
│       ├── schema.sql       # Database schema (13 tables)
│       ├── connection.py    # Async connection pool
│       └── models.py        # Data access layer
├── tests/                   # 362 tests
├── docker-compose.yml
├── pyproject.toml
└── README.md

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

git clone https://github.com/riyogarta/syne.git
cd syne
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Roadmap

• Core memory system with pgvector
• Google OAuth (free Gemini access)
• Telegram channel
• Anti-hallucination memory (3-layer)
• Conflict resolution (3-zone similarity)
• Ability system (bundled + self-created)
• Self-modification (abilities only)
• Multi-model support (6 drivers: Google, OpenAI, Anthropic, Groq, Together AI, Ollama)
• Interactive CLI mode
• Source code introspection (read_source)
• Systemd service auto-setup
• Sub-agents
• Multi-user access control
• File operations (read/write with security enforcement)
• Cron scheduler (DB-backed, once/interval/cron expressions)
• Telegram reactions (send/receive, 71 emojis)
• Voice message support (STT via Groq Whisper)
• Ollama embedding (local, $0 — qwen3-embedding with auto-install)
• Ability marketplace
• Web UI

License

Apache 2.0

Author: Riyogarta Pratikto

"I remember, therefore I am"