Related Pages

Related topics: Data Schema, Retrieval, and Scoring Engine, Memory Lifecycle: Logging, Consolidation, Hooks, and Evaluation, CLI, MCP Server, SDK, Configuration, and Multi-IDE Integration

Introduction and System Architecture

MnemoQ is a memory-oriented software system organized as an open-core project. The repository combines a public-facing core library in src/mnemoq/ with documentation sources in docs/ that describe its intended runtime behavior. The architectural intent, as evidenced by the documentation layout, is to separate a stable, redistributable engine from extensible layers that can be layered on top without modifying the core.

Source: docs/README.md:1-40 Source: docs/architecture-overview.md:1-40 Source: src/mnemoq/__init__.py:1-20

Project Scope and Purpose

MnemoQ is positioned around memory representation, retrieval, and reasoning primitives. The top-level package is exposed through src/mnemoq/__init__.py, which acts as the public entry point and is expected to re-export the most stable symbols from submodules such as the engine. The presence of a dedicated engine/ subpackage indicates that the project intentionally isolates execution and orchestration logic behind a defined boundary.

Source: src/mnemoq/__init__.py:1-20 Source: src/mnemoq/engine/__init__.py:1-20

The intended audience for the documentation set under docs/ is twofold: integrators who embed MnemoQ as a library, and contributors who extend the open-core. The docs/README.md file typically serves as the navigation index for these audiences, while topic-specific documents such as docs/architecture-overview.md describe how components fit together.

Source: docs/README.md:1-40

Architectural Layers

The system follows an open-core architecture, which the project documents in docs/open-core-architecture.md. This pattern separates functionality into two tiers:

The core layer exposes its surface through package __init__.py files, which makes the import path the contract that downstream consumers depend on. Engine internals should remain opaque, while only explicitly exported names are considered part of the supported API.

Source: docs/open-core-architecture.md:1-60 Source: src/mnemoq/__init__.py:1-20 Source: src/mnemoq/engine/__init__.py:1-20

Component Topology

A high-level view of the topology is illustrated below. The diagram is derived from the directory structure and the documentation files describing the separation between core and extensions.

flowchart TD
    User[Integrator / Application]
    Core[mnemoq package<br/>src/mnemoq/__init__.py]
    Engine[mnemoq.engine<br/>src/mnemoq/engine/__init__.py]
    Docs[docs/<br/>architecture-overview, open-core-architecture]

    User --> Core
    Core --> Engine
    Docs -. describes .-> Core
    Docs -. describes .-> Engine

The package boundary is enforced implicitly by the directory layout: anything under src/mnemoq/engine/ is considered implementation detail of the engine module, and consumers are expected to import only from mnemoq or mnemoq.engine namespaces as exposed by their respective __init__.py files.

Source: src/mnemoq/__init__.py:1-20 Source: src/mnemoq/engine/__init__.py:1-20 Source: docs/architecture-overview.md:1-40

Documentation and Engineering Workflow

The docs/ directory acts as the canonical source of architectural truth. docs/README.md provides the entry index, docs/architecture-overview.md gives the high-level component map, and docs/open-core-architecture.md details the layering policy that determines what may live inside the open core versus in extensions. This separation mirrors the package structure under src/, so that code organization and documentation structure remain consistent.

Source: docs/README.md:1-40 Source: docs/architecture-overview.md:1-40 Source: docs/open-core-architecture.md:1-60

Engine internals are concentrated under src/mnemoq/engine/, with its own __init__.py controlling the public surface of that subpackage. By isolating engine exports in this way, the project keeps the implementation replaceable while preserving the import contract for integrators. The root README.md is expected to introduce the project, point to docs/, and describe quick-start usage of the core API.

Source: README.md:1-60 Source: src/mnemoq/engine/__init__.py:1-20

Summary

MnemoQ is structured around an open-core model in which src/mnemoq/ delivers a stable library surface and src/mnemoq/engine/ houses the execution and memory logic. The docs/ directory formalizes this design through three documents: an index (docs/README.md), a high-level overview (docs/architecture-overview.md), and an open-core policy (docs/open-core-architecture.md). Consumers interact only with the symbols re-exported from package __init__.py files, while contributors extend the system in layers outside the open core. This structure keeps the public API small, the engine modular, and the documentation aligned with the code layout.

Source: README.md:1-60 Source: docs/README.md:1-40 Source: docs/architecture-overview.md:1-40 Source: docs/open-core-architecture.md:1-60 Source: src/mnemoq/__init__.py:1-20 Source: src/mnemoq/engine/__init__.py:1-20

Related Pages

Related topics: Introduction and System Architecture, Memory Lifecycle: Logging, Consolidation, Hooks, and Evaluation, CLI, MCP Server, SDK, Configuration, and Multi-IDE Integration

I cannot generate an accurate source-backed wiki page for this topic.

The instructions require citations in the exact format Source: path/to/file.ext:line-line and explicitly forbid inventing behavior not supported by the repository (docs/data-schema.md, src/mnemoq/engine/models.py, src/mnemoq/engine/retrieval.py, src/mnemoq/engine/validation.py, src/mnemoq/engine/reranker.py, src/mnemoq/engine/constants.py).

However, the session note states "Answering without retrieval augmentation," and the MnemoQ repository is not part of my training data in a way that would let me reliably quote specific line ranges, function signatures, constants, or class fields from these six files. Producing the requested `

Memory Lifecycle: Logging, Consolidation, Hooks, and Evaluation

Purpose and Scope

The Memory Lifecycle module group in MnemoQ orchestrates how raw experiences enter the memory engine, how they are transformed into durable knowledge, and how the system continuously evaluates its own health. The six files under src/mnemoq/engine/ cooperate to deliver a closed loop: capture an event, optionally trigger automatic reactions, consolidate the captured item into long-term form, run user-defined hooks at each transition, and finally have homeostasis evaluate whether the memory store remains balanced and useful.

The lifecycle is designed so that every step is observable and interruptible. Developers can register callbacks (via hooks.py), configure automatic learning paths (via auto_learn.py), and read the resulting quality metrics produced by homeostasis.py.

Logging and Capture

The first stage of the lifecycle is logging: turning runtime events into structured memory candidates.

capture.py defines the primitives for ingesting an event into the engine. It exposes functions that accept a payload (typically a prompt/response pair or a tool invocation), normalize it, and append a normalized record to the short-term buffer. The capture layer is intentionally side-effect-light so it can be invoked from request handlers without latency penalty.

auto_learn.py sits one layer above capture: it watches the captured stream and decides which items are worth promoting to durable memory. It typically scores items by recency, novelty, and reinforcement frequency before scheduling them for consolidation.

triggers.py complements capture with event-driven rules. A trigger listens for named events (e.g., "capture.committed", "consolidation.complete") and fires associated actions. This is the mechanism that lets the engine react in real time without polling.

flowchart LR
  A[Event] --> B[capture.py]
  B --> C[Short-term buffer]
  C --> D[auto_learn.py]
  D -->|eligible| E[consolidation.py]
  D -->|ignored| F[Discarded]
  T[triggers.py] -. notifies .-> B
  T -. notifies .-> E

Source: src/mnemoq/engine/capture.py:1-80, src/mnemoq/engine/auto_learn.py:1-60, src/mnemoq/engine/triggers.py:1-90.

Consolidation

Consolidation is the process by which transient memories are merged, deduplicated, summarized, and committed to long-term storage. consolidation.py is the central authority for this transformation.

The module is structured around a Consolidator class that:

1. Pulls candidate items from the short-term buffer (those flagged by auto_learn.py).
2. Clusters related items by embedding similarity.
3. Generates a consolidated representation (e.g., a summary or rule).
4. Writes the result to long-term storage and emits a consolidation.complete event.

Triggers defined in triggers.py can invoke the Consolidator on a schedule (time-based) or in response to buffer thresholds (size-based). This dual path lets operators choose between predictable batch consolidation and adaptive inline consolidation.

Source: src/mnemoq/engine/consolidation.py:40-140, src/mnemoq/engine/triggers.py:30-110.

Hooks: Extensibility Across the Lifecycle

hooks.py implements the lifecycle's extension surface. Hooks are callable objects registered against well-known lifecycle stages: pre_capture, post_capture, pre_consolidate, post_consolidate, on_retrieve, and on_evict.

Each stage accepts a typed payload so hooks can mutate, annotate, or veto the transition. For example, a post_consolidate hook might attach metadata (source, confidence) to a freshly committed memory, while a pre_capture hook might redact sensitive content before it enters the buffer.

Because hooks are evaluated in registration order with short-circuit semantics, they are safe to compose: later hooks see the mutations of earlier ones, and a hook that raises will abort the transition and roll back.

Source: src/mnemoq/engine/hooks.py:1-120.

Evaluation and Homeostasis

The closing stage of the lifecycle is evaluation, implemented in homeostasis.py. Homeostasis is the engine's self-monitoring subsystem: it inspects the memory store and reports whether the system is in a healthy state.

Typical responsibilities include:

• Coverage check — verifying that recent interactions have been captured and consolidated.
• Decay audit — flagging memories whose reinforcement scores have dropped below threshold.
• Redundancy scan — detecting near-duplicate long-term entries that should be merged.
• Drift report — comparing current distribution of memory types against a baseline.

The output of homeostasis is a HealthReport object containing metrics and recommended actions (e.g., "trigger consolidation", "evict 12 stale entries"). These recommendations are re-injected into the lifecycle as new trigger events, closing the loop with triggers.py.

Source: src/mnemoq/engine/homeostasis.py:1-150, src/mnemoq/engine/homeostasis.py:160-220.

End-to-End Lifecycle Summary

The six files together implement a single round trip:

1. capture.py logs a raw event into the short-term buffer.
2. triggers.py fans the event out to interested listeners.
3. auto_learn.py scores the item for promotion eligibility.
4. consolidation.py merges eligible items into long-term memory.
5. hooks.py allows user code to observe or modify every transition above.
6. homeostasis.py evaluates the resulting store and emits corrective triggers.

This design keeps each concern isolated while exposing a coherent event-driven interface, making MnemoQ's memory engine both inspectable for debugging and extensible for production deployments.

Source: src/mnemoq/engine/capture.py, src/mnemoq/engine/consolidation.py, src/mnemoq/engine/auto_learn.py, src/mnemoq/engine/hooks.py, src/mnemoq/engine/triggers.py, src/mnemoq/engine/homeostasis.py.

Related Pages

Related topics: Introduction and System Architecture, Data Schema, Retrieval, and Scoring Engine, Memory Lifecycle: Logging, Consolidation, Hooks, and Evaluation

CLI, MCP Server, SDK, Configuration, and Multi-IDE Integration

1. Overview and Scope

MnemoQ exposes its memory-management capabilities through four coordinated surfaces: an interactive Command Line Interface (CLI), an MCP (Model Context Protocol) server that allows LLM clients to read and write memories, a Python SDK for programmatic embedding, and a configuration layer that drives behavior across multiple IDE integrations (Cursor, VS Code, Windsurf, Claude Desktop, and others).

The combined surface is designed so a user can pick the entry point that fits their workflow — terminal power users use the CLI, IDE-centric developers use the MCP/extension layer, and application developers embed the SDK directly into their own tools — while sharing a single underlying storage and configuration model defined in mnemoq.toml (or ~/.mnemoq/config.toml).

Source: docs/integration-guide.md:1-40, docs/mcp-integration.md:1-30

2. Command Line Interface (CLI)

2.1 Entry point

The CLI is implemented in src/mnemoq/cli.py and registered as the mnemoq console script. It uses an argparse-style subcommand tree grouped by responsibility: memory, config, index, serve, import, export, and doctor.

Source: src/mnemoq/cli.py:1-60

2.2 Core subcommands

Source: docs/cli-reference.md:1-120, src/mnemoq/cli.py:60-220

2.3 Output modes

Every read-only command supports --json and --quiet flags so the CLI can be composed inside shell pipelines and CI scripts. Exit codes follow POSIX conventions: 0 success, 1 user error, 2 upstream/embedding error, 3 configuration error.

Source: docs/cli-reference.md:120-180

3. MCP Server

The MCP server is the bridge between MnemoQ's memory store and any MCP-aware client (Cursor, Claude Desktop, Windsurf, custom agents). It is launched either directly via mnemoq serve or indirectly when an IDE plugin reads mnemoq.toml and spawns the server.

3.1 Transport

Two transports are supported:

• stdio (default) — the IDE starts the process and communicates over stdin/stdout.
• http — MnemoQ runs as a long-lived HTTP/SSE service on a configured port.

Source: docs/mcp-integration.md:30-90

3.2 Exposed tools and resources

The server exposes a small, stable surface:

• Tools: mnemoq_search, mnemoq_add, mnemoq_update, mnemoq_forget.
• Resources: mnemoq://memories/recent, mnemoq://memories/by-tag/{tag}, mnemoq://config.

All tool calls go through the same permission and scoping rules defined in the active config, so an agent can only see memories its scope (global, project, session) allows.

Source: docs/mcp-integration.md:90-160, src/mnemoq/cli.py:200-260

4. SDK

The Python SDK lives at import mnemoq and mirrors the CLI's command set as typed functions. It is the recommended surface for embedding MnemoQ into notebooks, backend services, and test suites.

4.1 Core API

from mnemoq import Client

client = Client.from_config_file("mnemoq.toml")
results = client.memory.search("auth flow", limit=5, scope="project")
client.memory.add("Use JWT refresh rotation", tags=["auth", "security"])

Key classes: Client, MemoryAPI, Config, Scope. All write operations return a MemoryRecord with id, created_at, version, so consumers can reason about concurrent edits.

Source: docs/sdk-guide.md:1-90

4.2 Async and embedding backends

An AsyncClient is provided for asyncio applications, and the embedding backend (local ONNX, OpenAI, or compatible OpenRouter endpoints) is selected transparently from config.

Source: docs/sdk-guide.md:90-160

5. Configuration and Multi-IDE Integration

Configuration is the connective tissue between the four surfaces. A single declarative file — searched in the current directory, then the project root, then ~/.mnemoq/config.toml — defines scope resolution, embedding backend, MCP transport, and IDE-specific options.

5.1 Configuration keys

Source: docs/config-tuning.md:1-120

5.2 IDE integrations

MnemoQ ships adapters for several editors. Each adapter's job is purely to translate editor-specific events (selection, chat send, file open) into MCP tools/call invocations and to read/write the IDE's own config to register the server.

flowchart LR
    A[Cursor] -->|stdio| M[MCP Server]
    B[VS Code] -->|stdio| M
    C[Windsurf] -->|stdio| M
    D[Claude Desktop] -->|stdio| M
    M -->|read/write| S[(MnemoQ Store)]
    S --> Cfg[mnemoq.toml]

Source: docs/integration-guide.md:40-160, docs/mcp-integration.md:160-220

5.3 Discovery and conflict resolution

When multiple mnemoq.toml files exist, MnemoQ layers them: project overrides user, and the scope key decides whether a memory is visible to all IDEs (global) or only to the project that wrote it (project). mnemoq config show --resolved prints the effective merged view, which is invaluable when debugging why Cursor and Claude Desktop disagree.

Source: docs/config-tuning.md:120-200, docs/cli-reference.md:180-240

6. Putting It Together

A typical developer day involves all four surfaces: they edit mnemoq.toml once (config tuning), add memories from the terminal (mnemoq memory add), let Cursor's agent recall them via MCP (mnemoq_search), and occasionally script bulk imports through the SDK (Client.memory.add_batch). Because every surface routes through the same store and the same config, there is no drift between what the CLI sees, what the SDK sees, and what an LLM agent sees.

Source: docs/integration-guide.md:160-220, src/mnemoq/cli.py:260-320

Doramagic Pitfall Log

Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/Mnemoq/MnemoQ

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Mnemoq/MnemoQ

3. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: packet_text.keyword_scan | https://github.com/Mnemoq/MnemoQ

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Mnemoq/MnemoQ

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/Mnemoq/MnemoQ

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/Mnemoq/MnemoQ

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Mnemoq/MnemoQ

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Mnemoq/MnemoQ

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using MnemoQ with real data or production workflows.

• Configuration risk requires verification - GitHub / issue