Skip to content

Overview

SimpleContext is a Python library that gives AI agents a structured memory brain.

The Problem

Standard AI agent implementations keep conversation history as a flat list:

messages = [
    {"role": "user", "content": "msg1"},
    {"role": "assistant", "content": "reply1"},
    # ... 500 more messages
]

This approach fails at scale:

  • Context window overflow — you can't send everything to the LLM
  • Noisy retrieval — old, irrelevant messages dilute important context
  • No memory structure — facts, tasks, and chat history all mixed together
  • No evolution — information never consolidates or gains importance

The Solution: Tiered Memory

SimpleContext organizes memory into three tiers with different lifetimes and purposes:

Tier Purpose TTL
Working Active messages, current task state 2 hours
Episodic Session summaries, interaction history 30 days
Semantic Long-term facts, user knowledge, preferences Permanent

When building context for the LLM, SimpleContext:

  1. Plans retrieval based on detected intent
  2. Retrieves candidates from all relevant tiers
  3. Scores each node by relevance, importance, recency, and path
  4. Selects within token/character budget
  5. Builds a deterministic, structured prompt

Core Concepts

Intent Planning

SimpleContext detects the intent of each message and adjusts what it retrieves:

Intent Working Episodic Semantic Skills
conversation ✅ ✅ ❌ ❌
personal ✅ ❌ ✅ ❌
coding ✅ ✅ ✅ ✅
knowledge ❌ ❌ ✅ ❌
task ✅ ✅ ✅ ✅

Context Scoring

Every memory node gets a score before being included in context:

score = relevance×0.55 + importance×0.25 + recency×0.10 + path_priority×0.10

Nodes with higher scores are included first within the budget.

Fact Extraction

SimpleContext automatically extracts facts from conversations without an LLM:

User: "I'm working on a Python project using FastAPI"
→ Extracted fact: "user uses Python" (semantic tier, importance +0.1)
→ Extracted fact: "user project FastAPI" (semantic tier, importance +0.1)

Agent System

Agents are defined in YAML files and hot-reloaded without restarts. Each agent has:

  • Triggers — keywords that route messages to this agent
  • Personality — system prompt per user level (default/beginner/expert)
  • Skills — additional instructions injected into the system prompt
  • Chain rules — automatic handoff to other agents

Plugin System

Plugins extend SimpleContext via hooks that fire at key points in the processing pipeline. They can also declare app_commands to expose commands to any host application (Telegram bot, Discord, CLI, etc.).

Design Principles

  • Zero dependencies — only Python built-ins
  • Drop-in — copy the simplecontext/ folder, no install required
  • Backward compatible — v3 API still works in v4
  • Deterministic — same input always produces the same context structure
  • Hot-reload — agents and config changes without restarts