Memoryops

MemoryOps

[](https://github.com/Quazmoz/memoryops/actions/workflows/ci.yml) [](https://hub.docker.com/r/quazmoz/memoryops) [](https://www.rust-lang.org) [](LICENSE) [](#status) [](CONTRIBUTING.md)

> The Memory Operations Platform for AI Agents

MemoryOps is a self-hosted memory control plane for AI agents. It ingests engineering activity from GitHub, Slack, Jira, Linear, and agent observations, turns it into structured governed memory, and retrieves token-optimized context through API, MCP, and a control UI.

This is not a vector database, RAG wrapper, or agent framework. This is the control plane for what AI agents remember.

Status: MemoryOps is alpha. Core ingestion, retrieval, MCP, and control UI are functional, but APIs may change before v1.0.

---

Prerequisites

For the Quick Start (containerized):

• Docker + Docker Compose
• sqlx-cli (runs migrations against the Postgres container):

``bash cargo install sqlx-cli --no-default-features --features rustls,postgres ``

Only needed for local development (non-containerized):

• Rust stable (1.88.0+)
• Node.js 20+
• Ollama (optional, for local LLM): ollama pull llama3

---

Quick Start (Pre-built Images)

The fastest way to run MemoryOps — pull pre-built images from Docker Hub with no Rust or Node.js toolchain required.

# 1. Clone and configure
git clone https://github.com/Quazmoz/memoryops.git
cd memoryops
cp .env.example .env
# Set these two required secrets in .env:
#   APP_SECRET_KEY=
#   WORKSPACE_CREATION_SECRET=

# 2. Pull pre-built images and start everything
docker compose -f docker-compose.yml -f docker-compose.prebuilt.yml pull
docker compose -f docker-compose.yml -f docker-compose.prebuilt.yml up -d

# 3. Bootstrap a workspace
WORKSPACE_CREATION_SECRET= node scripts/bootstrap.mjs
# Save the returned workspace_id and api_key securely

# 4. Populate demo data for testing
API_KEY= WORKSPACE_ID= node scripts/seed.mjs

# 5. Access the UI
open http://localhost:5173

> [!TIP] > To pin a specific release instead of latest, set the tag in your environment: > ``bash > MEMORYOPS_TAG=api-0.1.0 MEMORYOPS_MCP_TAG=mcp-0.1.0 MEMORYOPS_FRONTEND_TAG=frontend-0.1.0 \ > docker compose -f docker-compose.yml -f docker-compose.prebuilt.yml up -d > ``

You can also pull the images individually:

docker pull quazmoz/memoryops:api-latest
docker pull quazmoz/memoryops:mcp-latest
docker pull quazmoz/memoryops:frontend-latest

---

Quick Start (Build from Source)

Get MemoryOps running by building from the current source. Requires Docker + Docker Compose.

# 1. Clone and configure
git clone https://github.com/Quazmoz/memoryops.git
cd memoryops
cp .env.example .env
# Set these two required secrets in .env:
#   APP_SECRET_KEY=
#   WORKSPACE_CREATION_SECRET=

# 2. Build and start everything using the current source
# This ensures the local code is compiled into the Docker images before startup.
docker compose build --no-cache api mcp frontend && docker compose up -d

# 3. Bootstrap a workspace
WORKSPACE_CREATION_SECRET= node scripts/bootstrap.mjs
# Save the returned workspace_id and api_key securely

# 4. Populate demo data for testing
API_KEY= WORKSPACE_ID= node scripts/seed.mjs

# 5. Access the UI
open http://localhost:5173

You now have a running MemoryOps instance with:

• API server on http://localhost:8080
• Frontend UI on http://localhost:5173
• Postgres, Redis, and Qdrant running in containers

> [!IMPORTANT] > When spinning up a local test in Docker, it is highly recommended to populate the demo data using scripts/seed.mjs. This provides initial memories (episodic, semantic, pinned) and tools to verify that search, retrieval, and UI components are functioning properly.

Note: First-time Docker builds may take several minutes on cold machines. Subsequent starts are instant.

---

The Problem

AI agents today:

• Forget everything across sessions
• Rely on prompt-stuffing hacks
• Use naive top-K retrieval with no context optimization
• Have zero memory governance or lifecycle management

Result: inconsistent agent behavior, repeated instructions, and hallucinations from stale context.

---

Why MemoryOps Exists

Engineering knowledge is distributed across PRs, incidents, tickets, chats, docs, and agent observations. Without a structured memory layer:

• Agents forget across sessions — Each conversation starts from zero, requiring repeated context stuffing
• Prompt stuffing does not scale — Token budgets are limited; pasting entire repos or chat logs is impractical
• Naive top-K retrieval fails — Simple similarity search returns stale or irrelevant context without lifecycle awareness
• Teams lack governance — No auditability, feedback loops, or visibility into what agents remember
• Multi-agent workflows break — Shared knowledge cannot be published or inherited across agent instances

MemoryOps provides a control plane for memory: structured ingestion, lifecycle governance, retrieval traces, feedback loops, and operator visibility.

---

Who is this for?

MemoryOps is designed for:

• AI platform engineers building coding or DevOps agents that need persistent project context across sessions
• DevOps/SRE/platform teams using agents for operational work and requiring memory persistence for runbooks, incidents, and infrastructure decisions
• Teams building multi-agent workflows that need shared semantic knowledge pools and workspace-level memory inheritance
• Self-hosted/local-AI teams with data-residency requirements who cannot use cloud-hosted memory services
• Researchers and prototypers needing memory lifecycle controls, retrieval traces, and feedback loops for agent experimentation

Probably not for you if:

• You only need a simple vector database without ingestion or lifecycle management
• You only want a hosted chatbot memory feature and don't need self-hosting
• Your team is not ready to operate self-hosted infrastructure (Postgres, Redis, Qdrant)
• You need verbatim-first local capture with minimal transformation (see comparison below)

---

What Can You Do With MemoryOps?

• Give your coding agent project context across sessions — No more repeating project structure, coding conventions, or architectural decisions
• Let support agents remember customer history — Automatically ingest from Slack/Jira and retrieve relevant past interactions
• Enable incident post-mortems with point-in-time queries — Reconstruct exactly what the system knew at any past timestamp
• Share semantic knowledge across multiple agents — Publish important decisions to a workspace pool that sub-agents inherit
• Govern memory lifecycle automatically — Configure decay, promotion, and pruning rules instead of manual cleanup
• Get retrieval explanations — See why each memory was selected with per-component scoring traces

---

What MemoryOps Does

| Layer | Capability | Why it matters | |-------|------------|----------------| | Ingestion | HMAC-validated webhooks from GitHub, Slack, Jira, Linear + agent observations endpoint | Turns engineering activity into structured events without manual data entry | | Processing | Event normalization, entity extraction, importance scoring (fast + async LLM paths) | Enriches raw events with context and prioritizes what matters | | Lifecycle | Episodic → semantic promotion, decay, deduplication, automatic pruning | Keeps memory relevant and manageable without manual cleanup |

| Retrieval | Token-aware context packing with hybrid semantic + BM25 search | Returns optimal context within token budgets, not just top-K results |

| Feedback | Per-memory ratings bias future retrieval via rolling relevance scores | System improves from agent and operator feedback over time | | Governance | Retrieval traces, audit log, pin/delete/merge, versioned agent library | Operators can inspect, control, and understand what agents remember | | MCP/API | Native Model Context Protocol server + REST API | Agents retrieve and store memory without HTTP glue code | | Control UI | Memory explorer, workspace settings, DLQ retry, health dashboard | Operators manage memory without touching the database |

---

MemoryOps vs. the Field

MemoryOps is designed for governed, inspectable, team-oriented agent memory. It is adjacent to vector databases, RAG wrappers, local-first memory tools, and managed memory APIs, but it focuses on the operational control plane around memory lifecycle and retrieval.

Where MemoryOps Fits

Memory Architecture Comparison (MemoryOps vs. OpenClaw vs. Nous Hermes)

MemoryOps vs. Verbatim-First Local Memory

Both approaches are valid. MemoryOps is optimized for teams that need governed, inspectable, multi-agent engineering memory. Verbatim-first local memory is attractive when the primary goal is faithful personal/project recall with minimal transformation.

| Dimension | MemoryOps | Verbatim-first / local-first memory systems | |-----------|-----------|--------------------------------------| | Primary goal | Governed engineering memory operations | Faithful local recall | | Ingestion model | Structured webhooks (GitHub, Jira) + Observations | Project/session mining, diaries, local capture | | Memory representation | Normalized episodic events → Semantic knowledge | Raw fidelity, minimal transformation | | Lifecycle governance | Decay, pruning, pinning, workspace publishing | Append-first, optional cleanup | | Retrieval transparency | Per-component scoring traces, feedback loops | Semantic similarity scores; less granular traceability | | Team/agent scope | Workspace pools, inheritance, multi-agent sharing | Primarily personal/project-scoped | | Best fit | Teams needing inspectable, governed agent memory | Individuals needing faithful local recall with minimal infrastructure |

Comparison discipline: MemoryOps avoids benchmark claims unless workloads, baselines, and scoring methods are reproducible. The comparison here focuses on architecture, control surfaces, and operational fit.

Retrieval Strategy

Memory Lifecycle

---

What Makes MemoryOps Different?

• Engineering-tool ingestion — Native webhooks for GitHub, Slack, Jira, Linear with HMAC validation
• Agent observations endpoint — Direct API for agents to submit observations and decisions
• Memory lifecycle — Episodic → semantic promotion, decay, deduplication, and automatic pruning
• Hybrid retrieval — Semantic + BM25 + token-aware packing with Reciprocal Rank Fusion
• Feedback loop — Per-memory ratings bias future retrieval via rolling relevance scores
• Retrieval traces — Per-component scoring explains why each memory was selected
• Control UI — Memory explorer, pin/delete/merge, audit log, and versioned agent library
• MCP server — Native Model Context Protocol server for Claude Code, VS Code, Open WebUI

• Self-hosted stack — Postgres, Redis, Qdrant with optional/local provider support

• Point-in-time queries — Reconstruct exact memory state at any past timestamp

---

Architecture

1. Engineering tools and agents send events or observations.
2. MemoryOps normalizes, scores, and stores events.
3. Lifecycle workers promote, decay, deduplicate, and prune memory.
4. Retrieval combines semantic search, BM25, feedback, and token-aware packing.
5. Agents consume context through REST or MCP.
6. Operators inspect and govern memory through the UI.

---

Full Setup (15 minutes)

For custom configuration, webhooks, integrations, and local development.

# 1. Clone and configure
git clone https://github.com/Quazmoz/memoryops.git
cd memoryops
cp .env.example .env
# Set required secrets and any optional providers

# 2. Start infrastructure
docker compose up -d postgres redis qdrant
docker compose ps  # Verify health checks pass

# 3. Run migrations
# Export DATABASE_URL from .env first:
#   bash/zsh: export $(grep -v '^#' .env | xargs)
#   PowerShell: Get-Content .env | ForEach-Object { if ($_ -match '^([^#][^=]*)=(.*)$') { [System.Environment]::SetEnvironmentVariable($matches[1].Trim(), $matches[2].Trim(), 'Process') } }
sqlx migrate run

# 4. Start API server
docker compose up -d api
# First build takes 2-5 min. Subsequent starts are instant.

# 5. Bootstrap workspace
WORKSPACE_CREATION_SECRET= node scripts/bootstrap.mjs

# 6. Start frontend with workspace ID
MEMORYOPS_WORKSPACE_ID= docker compose up -d --build frontend

# 7. (Optional) Start MCP server
docker compose up -d mcp

# 8. (Optional) Seed development data
API_KEY= node scripts/seed.mjs

| Service | URL | |---------|-----| | API | http://localhost:8080 | | Frontend | http://localhost:5173 | | MCP Server | http://localhost:3003 |

# Verify the API is healthy
curl http://localhost:8080/health/ready

See [docs/local-development.md](docs/local-development.md) for the complete local development guide including Ollama setup, port reference, and the test stack.

For hosting in production environments (such as Docker, Kubernetes, or K3s), see the [Production Deployment Guide](docs/deployment.md).

Note: You may see a Qdrant client/server version mismatch warning in the API logs (e.g., client 1.17 vs server 1.13). This is harmless for local development and API compatibility is maintained.

---

Resetting Local Environment

If you experience issues like a stale frontend image (e.g. ERREMPTYRESPONSE on port 5173), you can reset the non-persistent containers:

docker compose down
docker compose build --no-cache api frontend mcp
docker compose up -d postgres redis qdrant
sqlx migrate run
docker compose up -d api

Full Data Wipe

> WARNING: Destructive Operation

docker compose down -v

Using -v will delete the Postgres, Redis, and Qdrant volumes. Use this only if you want to permanently delete all local workspaces, memories, and start completely fresh.

---

Troubleshooting

| Issue | Solution | |-------|----------| | Port conflict on 5432 | Run lsof -i :5432 to see what's using the port. Stop your local Postgres instance, or remap the port in docker-compose.yml. | | Migrations fail | Ensure DATABASE_URL is exported in your active shell and the Postgres container is healthy (docker compose ps). | | Slow path jobs stuck in DLQ | Make sure Ollama is running and the model is pulled (ollama pull llama3). Retry jobs from the DLQ UI or via API. | | Frontend 404 on /v1 | The Vite proxy requires the API server to be running on 8080. Check that cargo run -p api or the API container is successfully running. | | Qdrant connection refused | Ensure the gRPC port 6334 is bound and exposed in docker-compose.yml (the Rust client connects via gRPC). | | Stale frontend image / ERREMPTYRESPONSE | The container may be using an old nginx config. Rebuild: docker compose build --no-cache frontend and force recreate docker compose up -d --force-recreate frontend. | | 401 Unauthorized | Check that the x-api-key header is present and correct. Regenerate keys from the Settings UI or via POST /v1/workspaces/{id}/keys. | | Embeddings not updating | Verify the processor worker is running and Redis is reachable. Check the DLQ for failed jobs. | | No search results | Trigger a re-index from Settings to rebuild the vector index. Ensure memories have been ingested. | | MCP not connecting | Ensure memoryops-mcp is on your PATH (or use cargo run -p mcp) and the env vars are set correctly. |

For more detailed troubleshooting, see [docs/local-development.md](docs/local-development.md).

---

Connecting AI

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Quazmoz
• Source: Quazmoz/memoryops
• License: MIT
• Homepage: https://consultant.quinnfavo.com

Install and usage instructions live in the source repository linked above.