dreamer-server 0.1.0

Self-hostable framework for developing coding-agent context from lived experience

Dreamer - self-evolving context for your coding agents

Get started · Extensions · Blogpost

Dreamer keeps your team's AGENTS.md and skills up to date with what your coding agents learn while they work. It runs as a self-hostable MCP server that collects memories from every agent on the team and, on a schedule, regenerates the context bundle the next session reads.

Team-wide memory. Memories from every agent on the team pool into a single store and feed a single context bundle, instead of staying on one workstation.

Any coding CLI. Anything that speaks MCP submits memories through the same submit_memory tool, including Claude Code, Cursor, Codex, and custom agents.

Extendible by config. STM store, LTM store, context store, dream engine, auth, triggers, and hooks are Python Protocols wired up from YAML. Swap any default by pointing at a different class.

Get started

Dreamer requires Python 3.12 or later. The defaults extra pulls in SQLite for STM, the Claude Agent SDK for dreaming, APScheduler for cron triggers, and gitpython for the post-dream commit hook.

pip install 'dreamer-server[defaults]'

Scaffold a project.

dreamer init

This writes a dreamer.yaml, a workspace/ with memory/ and context/ subdirectories, and a .gitignore that keeps the SQLite database out of git.

Issue a token for your agents to send in the Authorization header.

dreamer-simple-auth token create --db ./dreamer.db --name my-token

Sanity-check the config. The loader resolves every component, runs the protocol-conformance check, and prints the wired graph and per-slot multi-tenancy table.

dreamer config check

Run the server.

dreamer serve

Point Claude Code or any MCP client over streamable-http at http://localhost:8080/mcp/ with Authorization: Bearer <token>. The server advertises a submit_memory tool whose accepted types come from your config. Out of the box, those are observation, failure, and code_snippet.

Cron is the default trigger. To fire a one-shot dream from the command line:

dreamer dream --trigger external

Extensions

Dreamer is config-assembled. dreamer.yaml wires module.path.ClassName references into a component graph. Every slot sits behind a Python Protocol defined in dreamer.api, including the STM store, the LTM store, the context store, the dream engine, auth, triggers, and hooks. The shipped defaults are chosen to get a team running in a few minutes, and every one of them can be swapped.

stm_store:
  class: dreamer.contrib.stm.sqlite.SQLiteSTMStore
  params:
    path: ./data/stm.db

ltm_store:
  class: dreamer.contrib.ltm.markdown.MarkdownLTMStore
  params:
    root: ./workspace/memory

context_store:
  class: dreamer.contrib.context.markdown.MarkdownContextStore
  params:
    root: ./workspace/context

dream_engine:
  class: dreamer.contrib.dream.claude_agent.ClaudeAgentDreamEngine

triggers:
  - class: dreamer.contrib.triggers.cron.CronTrigger
    params:
      schedule: "0 */6 * * *"

To plug in your own component, write a class that satisfies the protocol. For example, a Postgres-backed STM store:

from typing import ClassVar
from dreamer.api.compat import implements
from dreamer.api.stores import STMStore

@implements(STMStore, version=1)
class PostgresSTMStore:
    multi_tenant: ClassVar[bool] = True

    def __init__(self, *, dsn: str) -> None:
        ...

    async def submit(self, memory, *, ctx): ...
    async def claim_batch(self, *, ctx): ...

Then reference it from dreamer.yaml:

stm_store:
  class: my_pkg.stores.PostgresSTMStore
  params:
    dsn: ${env:POSTGRES_DSN}

dreamer config check validates the protocol version, signatures, parameter kinds, and capability requirements before the server boots. The same shape of change covers a graph-backed long-term memory store, an OIDC auth backend, or a Slack notification hook in place of the git commit.

dreamer.testing.conformance ships abstract pytest classes for each protocol. The cases cover idempotency, lease isolation, expired-lease reclamation, tenant-scope leakage, and the purge_consumed contract. Any compliant implementation should pass them.

from dreamer.testing.conformance.stm_store import STMStoreConformance

class TestPostgresSTMStore(STMStoreConformance):
    @pytest.fixture
    async def store(self):
        return PostgresSTMStore(dsn="postgresql://...")

License

MIT. See LICENSE.