Skip to main content
Glama
MnemoQ
by Mnemoq

MnemoQ

Local-first memory engine for AI agents — MCP-native, graph-linked, spaced repetition.

Agent ──log──▶ MnemoQ Engine ──store──▶ learnings.jsonl
Agent ◀──retrieve── MnemoQ Engine ◀──read── learnings.jsonl
Agent ──MCP──▶ mnemoq-mcp ──read/write──▶ learnings.jsonl

PyPI version Python versions CI License: AGPL-3.0-or-later

Install

pip install mnemoq

CLI-only users (no Python project needed):

pipx install mnemoq

Related MCP server: Cortex

Quick Start

1. Scaffold a project

mnemoq-scaffold ./my-project --defaults

This creates a memory/ directory with config.json and learnings.jsonl in your project.

Wire memory into your IDE/agent platform:

mnemoq-scaffold ./my-project --defaults --ide windsurf
mnemoq-scaffold ./my-project --defaults --ide windsurf,cursor,claude-code
mnemoq-scaffold ./my-project --defaults --ide all
mnemoq-scaffold --ide ?

Supported platforms: opencode, windsurf, cursor, claude-code, copilot, all.

2. Log a learning

mnemoq --log '{"step":3,"source_agent":"claude","type":"pattern","domain":"backend","components":["api","auth"],"files_touched":["src/auth.py"],"trigger":"JWT validation failed on expired tokens","action":"Added explicit expiry check before signature verification","reason":"PyJWT silently accepts expired tokens when verify_exp is not set","importance":8,"severity":"major"}'

PowerShell-safe alternative (avoids JSON quoting issues):

mnemoq --log-file learning.json

3. Retrieve relevant learnings

mnemoq --step 3 --components api,auth --domain backend

4. Other commands

mnemoq --stats                          # Memory statistics
mnemoq --resolve 2025-06-25T10:30:00    # Mark a learning resolved
mnemoq --review-agents --step 3         # AGENTS.md section health report
mnemoq --consolidate                    # Archive + promote (sleep cycle)
mnemoq --install-hooks                  # Install git post-commit auto-learn hook

For the full retrieve → work → log → evaluate → auto-learn loop and how to wire it into any IDE or agent, see the Integration Guide.

5. MCP server

MCP is the primary integration path for AI agents. The server runs over stdio (JSON-RPC 2.0) with no HTTP dependency.

mnemoq-mcp                                # auto-discovers memory/ in cwd
mnemoq-mcp --memory-dir /path/to/memory   # explicit path

Or via environment variable: AGENT_MEMORY_DIR=/path/to/memory mnemoq-mcp

Tools exposed: retrieve_learnings, log_learning, resolve_learning, get_stats, consolidate

Works with Claude Desktop, Cursor, Windsurf, VS Code, and any MCP-compatible client. See the full MCP integration guide for client configuration snippets, tool reference, and troubleshooting.

CLI Reference

Command

Description

mnemoq

Log, retrieve, consolidate, and manage agent memories

mnemoq-scaffold

Initialize a new project with memory directory and config

mnemoq-update

Update engine files in existing projects

mnemoq-mcp

Start MCP server (JSON-RPC over stdio)

scripts/generate_fakes.py

Generate synthetic memory entries for testing

See docs/cli-reference.md for all flags, examples, and mutual-exclusion rules.

Configuration

memory/config.json tunes retrieval scoring, retention, embeddings, reranking, and access control for your project. Below is a summary of all parameters — see the full Config Tuning Guide for ranges, defaults, and tuning recipes.

Parameter

Default

What it controls

project_name

"<PROJECT_NAME>"

Project identifier

engine_min_version

"1.15.0"

Minimum engine version

schema_version

1

Config schema version

max_step

null

Cap on step values (null = no cap)

valid_domains

null

Accepted domain whitelist

valid_source_agents

null

Accepted agent whitelist

retrieval_only_agents

null

Agents that can retrieve but not log

domain_mappings

null

Custom domain → canonical tag mappings

api_key

null

HTTP API auth key (null = no auth)

embedding_model

"all-MiniLM-L6-v2"

sentence-transformers model name

embedding_cache_dir

"~/.agent-memory/models/"

Model file cache path

reranker

"none"

Reranker mode: none, cross-encoder, llm-local

reranker_top_n

20

Number of top results to rerank

reranker_model

"cross-encoder/ms-marco-MiniLM-L-12-v2"

Cross-encoder model name

reranker_llm_endpoint

null

LLM endpoint URL for llm-local mode

reranker_llm_model

null

LLM model name for llm-local mode

tuning.decay_rate

0.995

Exponential decay per step (recency)

tuning.score_threshold

0.15

Minimum score for non-critical candidates

tuning.component_weight

1.0

Weight when task components match

tuning.file_weight

0.7

Weight when task files match

tuning.domain_weight

0.4

Weight when domain matches

tuning.no_match_weight

0.1

Weight when nothing matches

tuning.max_warnings

5

Max critical entries per retrieval

tuning.max_patterns

15

Max non-critical entries per retrieval

tuning.minor_retention

5

Step window for minor entries

tuning.major_retention

20

Step window for major entries

tuning.escalation_threshold

30

Step age for escalation flagging

tuning.bm25_k1

1.5

BM25 term frequency saturation

tuning.bm25_b

0.75

BM25 document length normalization

tuning.rrf_k

60

Reciprocal rank fusion constant

tuning.embedding_alpha

0.5

Blend weight: alpha * rrf + (1-alpha) * cosine

tuning.semantic_dedup_threshold

0.85

Cosine similarity for duplicate detection

tuning.sleep_cycle_days

1

Days between consolidation triggers

tuning.sleep_cycle_quarantine_threshold

20

Quarantine count that triggers consolidation

Data Schema

Each entry in learnings.jsonl is a JSON object with these required fields:

Field

Type

Constraint

step

int

≥ 1

source_agent

str

must be a valid agent name

type

str

bug_fix, optimization, or architectural_pattern

domain

str

e.g. backend, testing, security

components

list[str]

non-empty

files_touched

list[str]

non-empty

trigger

str

must start with When

action

str

must contain ALWAYS or NEVER

reason

str

non-empty

importance

int

1–10

severity

str

minor, major, or critical

The engine auto-stamps ts, commit, access_count, reinforcement_count, embedding, schema_version, and provenance fields at log time. See docs/data-schema.md for the full reference including optional fields, enum values, schema versioning, and sample entries.

Development

git clone https://github.com/Mnemoq/MnemoQ.git
cd MnemoQ
pip install -e ".[dev]"
pytest

Structure

  • src/mnemoq/ — Engine source (CLI, retrieval, validation, consolidation, MCP server, dashboard, SDK)

  • src/mnemoq/engine/ — Core modules (retrieval, scoring, reranking, consolidation, validation, server)

  • tests/ — Test suite

  • templates/ — Config templates, prompts, eval data

  • docs/ — Architecture documentation (index)

  • scripts/ — Deploy scripts

Changelog

See CHANGELOG.md.

Roadmap

See docs/ROADMAP.md for current status and planned features.

License

AGPL-3.0-or-later. See LICENSE for details.

Contributing

See CONTRIBUTING.md. Submitting a PR constitutes acceptance of the CLA.

Security

Report vulnerabilities privately via GitHub Security Advisories. See SECURITY.md for details.

Available Tools

8 tools
capture_interactionA

Capture a conversation interaction as memory. Extracts learnable moments from raw text and auto-logs them. Three-tier extraction: online LLM, offline LLM, heuristic fallback.

Inputs: conversation (required), step.

consolidateB

Trigger a Sleep Cycle (consolidation): archives unresolved entries, generates promotion candidates, detects contradictions, and checks for stale entries.

Inputs: force, sprint_number.

evaluate_promptB

Evaluate a structured prompt summary for learnable moments. Runs heuristic detectors on the summary, auto-logs high-confidence signals, and returns suggestions for medium-confidence ones.

Inputs: step (required), outcome (required), components (required), prompt_type (required), +5 more.

get_statsA

Get memory system statistics: total entries, unresolved/resolved counts, severity/type/scope breakdowns, reinforcement patterns, and sleep cycle status.

Inputs: no named parameters.

log_learningA

Log a new learning entry. Validates, checks for duplicates/semantic duplicates, and appends to memory. Returns status (added/duplicate/semantic_duplicate/conflict/quarantined) and entry details.

Inputs: entry (required).

resolve_learningB

Mark an existing learning entry as resolved by its timestamp.

Inputs: timestamp (required).

retrieve_learningsA

Retrieve relevant learnings for the current task context. Returns warnings (critical issues) and patterns (architectural guidance), scored and ranked by relevance.

Inputs: step (required), files, domain, components.

review_agentsB

Diagnostic report on AGENTS.md section health. Cross-references recent learnings with AGENTS.md sections, categorizing sections as active (referenced by learnings), cold (no references), and identifying unmatched learnings.

Inputs: step (required), threshold.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: capturing raw interactions, logging structured learning, evaluating prompts, retrieving relevant learnings, resolving entries, consolidating memory, and reviewing agent documentation. No two tools overlap in function.

    Naming Consistency4/5

    Most tools follow a clear verb_noun pattern in snake_case (e.g., capture_interaction, log_learning, retrieve_learnings). However, 'consolidate' breaks the pattern as a single verb without a noun, causing a minor inconsistency.

    Tool Count5/5

    With 8 tools, the server covers core memory operations (create, read, update, consolidate, evaluate) without being overwhelming. The count is well-scoped for a memory management system.

    Completeness3/5

    The server lacks direct update and delete operations for learning entries, which are common in memory systems. While resolve_learning provides status change, editing entry content is missing. Retrieval is limited to context-based relevance, missing full listing.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Local-first memory engine that synthesizes entity profiles at ingestion. Enables persistent, reasoning memory for AI agents via MCP tools like add, search, and profile.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Local-first AI memory layer with hybrid retrieval and brain-inspired namespaces. Enables agents to save, search, and manage memories directly via MCP tools.
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Local-first, auditable memory for AI agents. Provides durable context for MCP hosts with SQLite storage, CLI, and MCP tools for memory management.
      2
      Apache 2.0
    • A
      license
      C
      quality
      A
      maintenance
      Provides AI agents with a human-inspired memory layer via MCP, enabling episodic and semantic memory recall, forgetting curves, consolidation, and contradiction detection. It integrates with MCP clients to offer local-first, dependency-free memory management.
      98
      1
      MIT