convez.ai
MCP ServerDados & AnalyticsAvançado
znasllc-io

memQL

znasllc-io/memql

Grafo de memória time-series com DSL única para agentes e voice

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que implementa um grafo de memória time-series nativo para IA com DSL unificada. Consolida conceitos, queries, workflows de agentes e voice em primitivos deployáveis, eliminando a necessidade de integrar manualmente vector stores, orquestradores e gateways de IA.

Instalação

$npx convez-ai znasllc-io/memql

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
0
Acompanhando
0
Saúde
75%
Último commit
há 1 dia
Versão
v0.31.39
Issues abertas
130
Contribuidores
4

Casos de uso

  • Construir agentes de IA com memória persistente e consistente
  • Declarar esquemas, queries e automações em uma única linguagem
  • Eliminar integração manual entre vector stores, workflows e modelos de IA
  • Prototipar sistemas de voice com estado compartilhado

Veredito

memQL é ambicioso em escopo — busca ser a cola entre memory, orchestration e inference. Ainda em alpha com breaking changes esperadas, mas o conceito de DSL unificada para agentes é sólido. Recomendado para times que querem experimentar infra de agentes em Go, não para produção imediata.

README

A tradução para o português deste README ainda está na fila.

Status: Alpha / pre-1.0 — not production-ready. memQL is under active development. The DSL, engine API, and wire surface are still evolving; expect breaking changes between commits. Suitable for experimentation, prototyping, and early-design feedback today.


What is memQL?

memQL is a distributed time-series memory graph with its own DSL — a single language for declaring concepts (schemas), queries, mutations, tools, and event-driven automations side-by-side, then executing them across specialized nodes.

It replaces the integration glue AI-native teams typically hand-write — vector store + workflow engine + AI gateway + voice stack — with one deployable primitive. A team that would otherwise stitch together four systems can declare an agent's memory, behavior, and triggers in one DSL file and run them on a memQL cluster.

Why memQL?

Agent and voice deployments today are integration-heavy. Most of the engineering effort is plumbing — keeping state consistent across a vector store, an orchestrator, a tool registry, and a model provider. memQL collapses that plumbing: concepts and queries live in the same place; tools, automations, and workflows reference them directly; the engine handles consistency, time-series storage, and execution.

Example

@version("1.0.0")
@namespace("acme")
concept ticket {
  id          string   @required
  subject     string   @required
  priority    string
  createdAt   datetime @required
}

@enabled
@handler(type="query", query="concept==v1:acme:ticket && ticket.priority==args.priority")
@executionTime("fast")
@description("List tickets by priority")
tool listByPriority {
  priority string @required
}

A concept (schema) and an LLM-callable tool in the same file, same language. Add queries, mutations, or event-driven automations right next to them.


Quick Start

# Start development environment (Docker)
docker compose -f docker/docker-compose.full.yml up --build

# Run tests
go test ./...

# Deploy to staging (Azure AKS)
make deploy VERSION=X

Full setup guide: docs/public/overview/quickstart.md


Documentation


Tech Stack

Backend

  • Language: Go 1.26.1+
  • Database: PostgreSQL 16 + TimescaleDB
  • API: gRPC (primary) + WebSocket bridge for browsers + HTTP for OAuth callbacks / health / file uploads
  • SI: Centralized provider system (OpenAI, Anthropic) on MemqlService.Stream
  • Auth: in-house identity service (magic-link + JWT, JWKS-published)

Query Language

  • MemQL DSL: Custom query language for time-series graphs
  • Automations: Event-driven workflows (.memql files)
  • Functions: Reusable query functions (.memql files)

Environments

Development (Docker)

  • Database: Local PostgreSQL + TimescaleDB container
  • Service: Local memQL container
  • Access: All developers
  • Command: docker compose -f docker/docker-compose.full.yml up --build

Staging (Cloud)

  • Database: TimescaleDB Cloud (Tiger Cloud)
  • Service: Azure Kubernetes Service (AKS, cluster aks-memql-staging)
  • Access: All developers
  • Command: make deploy VERSION=X

Production (Cloud)

  • Database: TimescaleDB Cloud (Tiger Cloud) - separate instance
  • Service: Azure Kubernetes Service (AKS)
  • Access: Senior/Lead developers only
  • Deploy: Promote a validated version (see docs/public/operate/deployment-strategy.md)

Full details: docs/public/overview/tech-stack.md


Development

Prerequisites

Hardware:

  • macOS with Apple Silicon (M1/M2/M3)
  • MacBook Pro or MacBook Air
  • 16GB RAM minimum (32GB recommended)

Software:

  • Go 1.26.1+ (ARM64 build)
  • Docker Desktop for Mac (Apple Silicon)
  • Azure CLI (az) + kubectl
  • git

Local Development Workflow

  1. Clone repository

    git clone https://github.com/znasllc-io/memql.git
    cd memql
    
  2. Start development environment

    docker compose -f docker/docker-compose.full.yml up --build
    
  3. Make changes and test

    # Edit code
    # ...
    
    # Run tests
    go test ./...
    
    # View logs
    docker compose -f docker/docker-compose.full.yml logs -f
    
  4. Deploy to staging for integration testing

    make deploy VERSION=X
    
  5. Commit to main (focused commits) or open a feature branch + PR when review is genuinely useful. Stage by explicit path:

    git add path/to/changed.file
    git commit -m "domain: imperative subject"
    git push origin main
    

Project Structure

memQL/
├── main.go                 # Entry point (thin orchestrator)
├── app/                    # Phased service bootstrap
│   ├── app.go             # Build() orchestrator
│   ├── config.go          # Config + auth
│   ├── database.go        # Database + concepts
│   ├── engine.go          # Engine + bus + automations
│   ├── integrations.go    # Integration providers
│   ├── transport.go       # gRPC + HTTP + WebSocket
│   ├── cluster.go         # Distributed node bootstrap
│   └── adapters.go        # Engine adapter types
├── component/              # Go service components
│   ├── memql/             # Core query engine
│   ├── database/          # Database providers
│   ├── server/            # HTTP/WebSocket servers
│   └── auth/              # Authentication
├── integrations/          # External service integrations
│   ├── cognition/         # SI collaboration
│   └── audio/             # Audio streaming
├── automations/           # MemQL DSL automations (.memql)
├── queries/               # MemQL DSL query functions (.memql)
├── mutations/             # MemQL DSL mutation functions (.memql)
├── specs/                 # MemQL DSL specification predicates (.memql)
├── tools/                 # MemQL DSL SI tool definitions (.memql)
├── docs/                  # Documentation
│   ├── core/              # Architecture, language
│   ├── api/               # API references
│   ├── guides/            # How-to guides
│   └── auth/              # Authentication
├── docker/                # Docker configuration
└── .claude/               # Configuration

Common Commands

TaskCommand
Start Docker stackdocker compose -f docker/docker-compose.full.yml up --build
Stop Docker servicesdocker compose -f docker/docker-compose.full.yml down
Run Go test suitego test ./...
Deploy to stagingmake deploy VERSION=X
View container logsdocker compose -f docker/docker-compose.full.yml logs -f
Database shellpsql postgres://memql:memql_dev@localhost:5432/memql

Authentication

Every environment authenticates against the in-house identity service (component/identity):

  • Magic-link sign-in (no passwords)
  • OAuth-style code exchange for SPAs (/oauth/token)
  • JWKS-published EdDSA signing keys (/.well-known/jwks.json)
  • Role-based access control (RBAC) per v1:identity:user.role
  • Centralized user / partition-access management at /admin/

Developer access:

  • Development: All developers (own machine)
  • Staging: All developers (shared testing)
  • Production: Senior/Lead developers only (live system)

Testing

# Run all tests
go test ./...

# Run specific package tests
go test -v ./component/memql/...

# Run with coverage
go test -cover ./...

Docker

Development Stack

Full stack with PostgreSQL + TimescaleDB + memQL service:

# Start everything
docker compose -f docker/docker-compose.full.yml up --build

# View logs
docker compose -f docker/docker-compose.full.yml logs -f

# Access database
psql postgres://memql:memql_dev@localhost:5432/memql

# Stop (preserves data)
docker compose -f docker/docker-compose.full.yml down

Documentation: docker/README.md


MemQL Language

MemQL DSL is a domain-specific query language for time-series memory graphs.

Example Query

// Find recent utterances in a space
spaceUtterances({
  "spaceId": "space_123",
  "limit": 10
})

Example Automation

@enabled
@trigger(event="graph.node.created.v1:cognition:participant")
@description("Auto-join SI agents to spaces")
func (Automation) autoJoinSI() {
  // Automation logic...
}

Full reference: docs/public/language/memql.md


Deployment

memQL runs on Azure Kubernetes Service (AKS). Deploy to staging with make deploy VERSION=X (scripts/deploy/aks-deploy.sh); production promotes a validated version.

See docs/public/operate/deployment-strategy.md for deploy/topology (cluster aks-memql-staging, ACR acrmemql.azurecr.io, Tiger Cloud DB, the migration + smoke gates, and the staging → prod promotion flow).


Contributing

  1. Read docs/public/overview/tech-stack.md
  2. Make changes and test in development environment (go test ./...)
  3. Deploy to staging for integration testing
  4. Commit directly to main for focused changes, or open a PR when review is useful
  5. Stage files by explicit path (git add <file>)

Git workflow: Single long-lived main branch. Pre-release: no backwards-compat shims; fix both memQL and the consumer at once.


License

Apache License 2.0 — see LICENSE.


Need Help?

  1. Quick start: docs/public/overview/quickstart.md
  2. Find documentation: GLOSSARY.md
  3. Tech stack details: docs/public/overview/tech-stack.md
  4. Component docs: Check directory CLAUDE.md files
  5. Issues: Create GitHub issue

memQL - Time-series memory graph database for SI-powered collaboration

Ver o original no GitHub

Bom para

Relacionados