memql

README

memQL

AI-native time-series memory graph with a single DSL.
Unifies concepts, queries, agent workflows, and voice into deployable primitives.

_{Designed and built with Claude as co-author.}

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 (Google Cloud Run)
gcloud run deploy

Full setup guide: QUICKSTART.md

---

Documentation

• CLAUDE.md - Project overview and architecture
• QUICKSTART.md - 5-minute setup guide
• GLOSSARY.md - Complete documentation index
• TECH_STACK_AND_PRACTICES.md - Tech stack and deployment practices

---

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: Google Cloud Run (us-central1)
• Access: All developers
• Command: gcloud run deploy

Production (Cloud)

• Database: TimescaleDB Cloud (Tiger Cloud) - separate instance
• Service: Google Cloud Run (production)
• Access: Senior/Lead developers only
• Deploy: Automatic via CI/CD on merge to main

Full details: TECH_STACK_AND_PRACTICES.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)
• gcloud CLI
• 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

   gcloud run deploy
   

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

Task	Command
Start Docker stack	docker compose -f docker/docker-compose.full.yml up --build
Stop Docker services	docker compose -f docker/docker-compose.full.yml down
Run Go test suite	go test ./...
Deploy to staging	gcloud run deploy
View container logs	docker compose -f docker/docker-compose.full.yml logs -f
Database shell	psql 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/core/memql.md

---

Deployment

Staging Environment

# Deploy latest code to staging (Google Cloud Run)
gcloud run deploy

# View logs
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=memql-anequim" --limit 50

Production Environment

• Automatic deployment via CI/CD when code is merged to main branch
• Manual deployment requires production access permissions
• Always test in staging before deploying to production

---

Contributing

1. Read TECH_STACK_AND_PRACTICES.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: QUICKSTART.md
2. Find documentation: GLOSSARY.md
3. Tech stack details: TECH_STACK_AND_PRACTICES.md
4. Component docs: Check directory CLAUDE.md files
5. Issues: Create GitHub issue

---

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