Skip to main content
Glama
Mnemoq

MnemoQ

Official
by Mnemoq
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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: GroundMemory

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.

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Mnemoq/MnemoQ'

If you have feedback or need assistance with the MCP directory API, please join our Discord server