Skip to content

Configuration

SimpleContext uses a YAML config file. All fields are optional — defaults work out of the box.

Full Reference

# config.yaml

simplecontext:
  version: "4.3"

# ── Storage ──────────────────────────────────────────────
storage:
  backend: sqlite          # sqlite | memory | redis | postgresql
  path: ./sc_data.db       # SQLite only

  # Redis
  # backend: redis
  # url: redis://localhost:6379/0
  # prefix: sc

  # PostgreSQL
  # backend: postgresql
  # dsn: postgresql://user:pass@localhost:5432/mydb

# ── Memory ───────────────────────────────────────────────
memory:
  default_limit: 20        # max messages from get_for_llm()
  max_per_user: 1000       # max total nodes per user

  ttl_hours:
    working: 2             # working nodes expire after 2h
    episodic: 720          # episodic nodes expire after 30 days
    # semantic: null       # semantic nodes never expire (default)

  compression:
    enabled: false         # auto-compress old messages
    threshold: 50          # compress when message count exceeds this
    keep_last: 10          # keep last N messages intact before compressing

# ── Agents ───────────────────────────────────────────────
agents:
  folder: ./agents         # folder containing *.yaml agent files
  hot_reload: true         # reload when YAML files change (no restart needed)
  default: general         # fallback agent when no agent matches

# ── Skills ───────────────────────────────────────────────
skills:
  inheritance_depth: 5     # max depth for skill group inheritance

# ── Plugins ──────────────────────────────────────────────
plugins:
  enabled: true
  folder: ./plugins        # folder containing plugin *.py files

  # Per-plugin config (key = plugin name)
  # vector_search_plugin:
  #   enabled: true
  #   provider: local
  #   top_k: 5
  #   min_score: 0.15
  #   tiers: [semantic, episodic]
  #
  # logger_plugin:
  #   enabled: true
  #   log_path: ./sc.log

# ── Export ───────────────────────────────────────────────
export:
  folder: ./exports        # folder for export files

# ── Debug ────────────────────────────────────────────────
debug:
  retrieval: false         # log full retrieval pipeline details

Minimal Config

The smallest valid config that runs with SQLite:

storage:
  backend: sqlite
  path: ./data.db

agents:
  folder: ./agents

Config via Code

Override any config value programmatically using __ as a path separator:

sc = SimpleContext(
    "config.yaml",
    storage__backend    = "sqlite",
    storage__path       = "./my.db",
    agents__folder      = "./agents",
    agents__hot_reload  = True,
    agents__default     = "general",
    plugins__enabled    = True,
    memory__default_limit = 30,
    debug__retrieval    = False,
)

Storage Backends

Zero install. Best for development and single-instance deployments.

storage:
  backend: sqlite
  path: ./sc_data.db

In-memory only. Data lost on restart. Best for testing.

storage:
  backend: memory

pip install redis>=5.0

storage:
  backend: redis
  url: redis://localhost:6379/0
  prefix: sc

pip install psycopg2-binary>=2.9

storage:
  backend: postgresql
  dsn: postgresql://user:pass@localhost:5432/mydb

Per-Plugin Configuration

Each plugin reads its config from the plugins.<plugin_name> section:

plugins:
  enabled: true
  folder: ./plugins

  vector_search_plugin:
    enabled: true
    provider: local        # local | openai | ollama
    top_k: 5
    min_score: 0.15
    inject_as_system: true
    tiers: [semantic, episodic]
    # For OpenAI:
    # provider: openai
    # openai_api_key: sk-...
    # openai_model: text-embedding-3-small
    # For Ollama:
    # provider: ollama
    # ollama_url: http://localhost:11434
    # ollama_model: nomic-embed-text

  logger_plugin:
    enabled: true
    log_path: ./sc.log
    log_skills: false

  timestamp_plugin:
    enabled: true
    format: "%Y-%m-%d %H:%M UTC"

Environment Variables

Sensitive values (API keys, DSNs) should not be in config.yaml. Use environment variables and reference them in your code:

import os
sc = SimpleContext(
    "config.yaml",
    storage__dsn=os.environ["DB_DSN"],
)